@forgeax/engine-render 0.1.32 → 0.1.34

package/src/__tests__/volumetric-fog-stage-readback.dawn.test.ts

@@ -3,6 +3,8 @@ import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
 import { buildEngineShaderManifest } from '@forgeax/engine-vite-plugin-shader';
 import { describe, expect, it } from 'vitest';
 import { BYTES_PER_DIRECT_LIGHT_SLOT } from '../light-buffer-layout';
+import { VIEW_UNIFORM_BYTES } from '../record/view-ubo';
+import { VOLUMETRIC_FOG_PARAMS_BYTES } from '../volume/resources';
 
 const MAP_READ = 0x0001;
 const BUFFER_COPY_DST = 0x0008;
@@ -19,6 +21,13 @@ const BYTES_PER_PIXEL = 8;
 const MAX_CLUSTER_LIGHTS = 256;
 const CLUSTER_LIGHT_DATA_BYTES = MAX_CLUSTER_LIGHTS * BYTES_PER_DIRECT_LIGHT_SLOT;
 const CLUSTER_UNIFORM_BYTES = 32;
+const VOLUME_BOUNDS_MIN_Z = 0.1;
+const VOLUME_BOUNDS_MAX_Z = 0.9;
+const NON_UNIFORM_BOUNDS_MAX_Z = 8.1;
+const MAX_NON_UNIFORM_BEER_ERROR = 0.001;
+const NON_UNIFORM_EXTINCTION = 0.05;
+const MIN_NON_UNIFORM_REFERENCE_SEPARATION = 0.05;
+const MIN_NON_UNIFORM_GPU_SEPARATION = 0.05;
 const engineManifest = await buildEngineShaderManifest();
 
 interface StageValues {
@@ -33,6 +42,110 @@ interface VolumeStageReadbacks {
   readonly integrate: StageValues;
 }
 
+interface StageReadbackOptions {
+  readonly owners?: number;
+  readonly secondDensity?: number;
+  readonly thinSeparated?: boolean;
+  readonly reverse?: boolean;
+  readonly sceneDepthClear?: number;
+  readonly densityByte?: number;
+  /** Optional RGBA8 density field for the production integrate stage. */
+  readonly densityData?: Uint8Array;
+  readonly boundsMinZ?: number;
+  readonly boundsMaxZ?: number;
+  readonly maxDistance?: number;
+  readonly viewDepthScale?: number;
+  readonly extinction?: number;
+  readonly frameIndex?: number;
+  /** Depth clear used by the stable shadow receiver fixture. */
+  readonly shadowDepthClear?: number;
+  /** Unshadowed punctual light isolates ray integration from packed visibility. */
+  readonly localLight?: 'point' | 'spot';
+  /** Uniform-step diagnostic; omitted means the untouched production shader. */
+  readonly integratorStepCount?: number;
+}
+
+interface DensityField {
+  readonly data: Uint8Array;
+  readonly zRed: readonly number[];
+}
+
+function createNonUniformDensityField(redValues?: readonly number[]): DensityField {
+  const data = new Uint8Array(4 * SIZE * SIZE * SIZE);
+  const zRed: number[] = [];
+  for (let z = 0; z < SIZE; z += 1) {
+    // Keep X/Y constant. The default field changes only the first Z texel;
+    // the fine-density probe supplies a faster, seam-matched sequence.
+    // The exercised camera ray crosses the first-to-second texel transition
+    // under all three production density scales, so flattening the field to
+    // its first texel produces a measurable, independently falsifiable result.
+    const red = redValues?.[z] ?? (z === 0 ? 128 : 255);
+    zRed.push(red / 255);
+    for (let y = 0; y < SIZE; y += 1) {
+      for (let x = 0; x < SIZE; x += 1) {
+        const offset = ((z * SIZE + y) * SIZE + x) * 4;
+        data[offset] = red;
+        data[offset + 1] = 255;
+        data[offset + 2] = 255;
+        data[offset + 3] = 255;
+      }
+    }
+  }
+  return { data, zRed };
+}
+
+function createFlattenedDensityField(field: DensityField): DensityField {
+  const red = Math.round((field.zRed[0] ?? 0) * 255);
+  const data = new Uint8Array(4 * SIZE * SIZE * SIZE);
+  for (let z = 0; z < SIZE; z += 1) {
+    for (let y = 0; y < SIZE; y += 1) {
+      for (let x = 0; x < SIZE; x += 1) {
+        const offset = ((z * SIZE + y) * SIZE + x) * 4;
+        data[offset] = red;
+        data[offset + 1] = 255;
+        data[offset + 2] = 255;
+        data[offset + 3] = 255;
+      }
+    }
+  }
+  return { data, zRed: Array.from({ length: SIZE }, () => red / 255) };
+}
+
+function sampleClampedLinear(values: readonly number[], coordinate: number): number {
+  const scaled = coordinate * values.length - 0.5;
+  const lower = Math.floor(scaled);
+  const upper = lower + 1;
+  const interpolation = scaled - lower;
+  const clampIndex = (index: number): number => Math.max(0, Math.min(values.length - 1, index));
+  const lowerValue = values[clampIndex(lower)] ?? 0;
+  const upperValue = values[clampIndex(upper)] ?? 0;
+  return lowerValue + (upperValue - lowerValue) * interpolation;
+}
+
+function nonUniformScatteringDensity(field: DensityField, worldZ: number): number {
+  let grain = sampleClampedLinear(field.zRed, (worldZ * 0.1) % 1) + 0.5;
+  grain *= sampleClampedLinear(field.zRed, (worldZ * 0.05) % 1) + 0.5;
+  grain *= sampleClampedLinear(field.zRed, (worldZ * 0.02) % 1) + 0.5;
+  return Math.max(2 * grain - 1, 0);
+}
+
+function nonUniformBeerReference(
+  field: DensityField,
+  extinction = 1,
+  sampleCount = 16_384,
+  boundsMinZ = VOLUME_BOUNDS_MIN_Z,
+  boundsMaxZ = VOLUME_BOUNDS_MAX_Z,
+): number {
+  const interval = boundsMaxZ - boundsMinZ;
+  const segmentLength = interval / sampleCount;
+  let opticalDepth = 0;
+  for (let sample = 0; sample < sampleCount; sample += 1) {
+    const worldZ = boundsMinZ + (sample + 0.5) * segmentLength;
+    opticalDepth += nonUniformScatteringDensity(field, worldZ) * segmentLength;
+  }
+  return Math.exp(-extinction * opticalDepth);
+}
+
 function halfToFloat(bits: number): number {
   const sign = (bits & 0x8000) === 0 ? 1 : -1;
   const exponent = (bits >>> 10) & 0x1f;
@@ -42,12 +155,50 @@ function halfToFloat(bits: number): number {
   return sign * 2 ** (exponent - 15) * (1 + fraction / 1024);
 }
 
+function firstStageValue(values: readonly number[], label: string): number {
+  const value = values[0];
+  if (value === undefined) throw new Error(`missing stage readback value: ${label}`);
+  return value;
+}
+
 function manifestShader(marker: string): string {
   const entry = engineManifest.entries.find(({ wgsl }) => wgsl.includes(marker));
   if (entry === undefined) throw new Error(`missing cooked shader entry: ${marker}`);
   return entry.wgsl;
 }
 
+function productionIntegratorShader(stepCount?: number): string {
+  const source = manifestShader('fn volume_integrate');
+  if (stepCount === undefined) return source;
+  if (!Number.isInteger(stepCount) || stepCount < 1) {
+    throw new Error(`invalid production integrator step count: ${stepCount}`);
+  }
+  const functionStart = source.indexOf('fn volume_integrate');
+  if (functionStart < 0) throw new Error('production integrator function missing');
+  const prefix = source.slice(0, functionStart);
+  const body = source.slice(functionStart);
+  // The cooked manifest constant-folds the source-level loop count into the
+  // step-length divisor and loop guard. Replace both literals in that one
+  // production function to compile the same WGSL with a diagnostic schedule;
+  // an omitted override always exercises the unmodified production manifest.
+  // Diagnostic schedules disable local refinement to expose the old defect.
+  const productionCount = body.match(/< (\d+)u\b/)?.[1];
+  if (productionCount === undefined) throw new Error('production ray loop count missing');
+  const stepLengthMarker = new RegExp(`f32\\(${productionCount}u\\)`, 'g');
+  const loopGuardMarker = new RegExp(`< ${productionCount}u\\b`, 'g');
+  const stepLengthOccurrences = body.match(stepLengthMarker)?.length ?? 0;
+  const loopGuardOccurrences = body.match(loopGuardMarker)?.length ?? 0;
+  if (stepLengthOccurrences !== 1 || loopGuardOccurrences !== 1) {
+    throw new Error(
+      `production integrator step markers: length=${stepLengthOccurrences}, guard=${loopGuardOccurrences}`,
+    );
+  }
+  return `${prefix}${body
+    .replace(stepLengthMarker, `f32(${stepCount}u)`)
+    .replace(loopGuardMarker, `< ${stepCount}u`)
+    .replace(/select\(1u, 4u,/, 'select(1u, 1u,')} `;
+}
+
 function identityMatrix(target: Float32Array, offset: number): void {
   target[offset] = 1;
   target[offset + 5] = 1;
@@ -74,12 +225,19 @@ async function requestDevice(): Promise<RhiDevice> {
 }
 
 async function runInjectReadback(
-  sceneDepthClear = 1,
-  densitySource: number | 'height-gradient' | 'depth-gradient' = 255,
-  heightOffset = 0,
-  frameIndex = 0,
-  slopedShadow = false,
+  options: StageReadbackOptions = {},
 ): Promise<VolumeStageReadbacks> {
+  const sceneDepthClear = options.sceneDepthClear ?? 1;
+  const densityByte = options.densityByte ?? 255;
+  const boundsMinZ = options.boundsMinZ ?? VOLUME_BOUNDS_MIN_Z;
+  const boundsMaxZ = options.boundsMaxZ ?? VOLUME_BOUNDS_MAX_Z;
+  const maxDistance = options.maxDistance ?? 2;
+  const viewDepthScale = options.viewDepthScale ?? 1;
+  const extinction = options.extinction ?? 1;
+  const frameIndex = options.frameIndex ?? 0;
+  const shadowDepthClear = options.shadowDepthClear ?? 1;
+  const integratorStepCount = options.integratorStepCount;
+  const owners = options.owners ?? 1;
   const device = await requestDevice();
   const moduleResult = await createShaderModule(device, {
     code: manifestShader('fn volume_inject'),
@@ -91,7 +249,7 @@ async function runInjectReadback(
     label: 'stage-readback.volume-temporal',
   });
   const integrateModule = await createShaderModule(device, {
-    code: manifestShader('fn volume_integrate'),
+    code: productionIntegratorShader(integratorStepCount),
     label: 'stage-readback.volume-integrate',
   });
   if (!temporalModule.ok) throw temporalModule.error;
@@ -119,9 +277,17 @@ async function runInjectReadback(
     usage: TEXTURE_BINDING | TEXTURE_COPY_DST,
     textureBindingViewDimension: undefined,
   });
+  const secondDensityTexture = device.createTexture({
+    label: 'stage-readback.second-density',
+    size: { width: SIZE, height: SIZE, depthOrArrayLayers: SIZE },
+    dimension: '3d',
+    format: 'rgba8unorm',
+    usage: TEXTURE_BINDING | TEXTURE_COPY_DST,
+    textureBindingViewDimension: undefined,
+  });
   const outputTexture = device.createTexture({
     label: 'stage-readback.froxel',
-    size: { width: SIZE, height: SIZE, depthOrArrayLayers: PACKED_LAYERS },
+    size: { width: SIZE, height: SIZE, depthOrArrayLayers: PACKED_LAYERS * owners },
     dimension: '2d',
     format: 'rgba8unorm',
     usage: STORAGE_BINDING | TEXTURE_COPY_SRC | TEXTURE_BINDING,
@@ -166,6 +332,7 @@ async function runInjectReadback(
     !sceneDepthTexture.ok ||
     !shadowTexture.ok ||
     !densityTexture.ok ||
+    !secondDensityTexture.ok ||
     !outputTexture.ok ||
     !historyTexture.ok ||
     !temporalTexture.ok ||
@@ -179,6 +346,7 @@ async function runInjectReadback(
   if (!sceneDepthView.ok || !shadowView.ok)
     throw new Error('Dawn volume stage readback unavailable: depth view allocation failed');
   const densityView = createView(device, densityTexture.value, '3d');
+  const secondDensityView = createView(device, secondDensityTexture.value, '3d');
   const outputView = createView(device, outputTexture.value, '2d-array');
   const historyView = createView(device, historyTexture.value, '2d');
   const temporalView = createView(device, temporalTexture.value, '2d');
@@ -186,12 +354,12 @@ async function runInjectReadback(
   const projectorView = createView(device, projectorTexture.value, '2d');
   const viewBuffer = device.createBuffer({
     label: 'stage-readback.view',
-    size: 960,
+    size: VIEW_UNIFORM_BYTES,
     usage: 0x0040 | BUFFER_COPY_DST,
   });
   const paramsBuffer = device.createBuffer({
     label: 'stage-readback.params',
-    size: 128,
+    size: VOLUMETRIC_FOG_PARAMS_BYTES,
     usage: 0x0040 | BUFFER_COPY_DST,
   });
   const lightDataBuffer = device.createBuffer({
@@ -206,7 +374,7 @@ async function runInjectReadback(
   });
   const injectReadback = device.createBuffer({
     label: 'stage-readback.inject',
-    size: BYTES_PER_ROW * SIZE * PACKED_LAYERS,
+    size: BYTES_PER_ROW * SIZE * PACKED_LAYERS * owners,
     usage: MAP_READ | BUFFER_COPY_DST,
   });
   const temporalReadback = device.createBuffer({
@@ -230,30 +398,63 @@ async function runInjectReadback(
   )
     throw new Error('Dawn volume stage readback unavailable: readback allocation failed');
 
-  const viewData = new Float32Array(240);
+  const viewData = new Float32Array(VIEW_UNIFORM_BYTES / Float32Array.BYTES_PER_ELEMENT);
   for (const offset of [0, 28, 44, 60, 76, 92, 196, 212]) identityMatrix(viewData, offset);
+  viewData[44 + 10] = viewDepthScale;
   viewData[24] = 0;
-  viewData[25] = heightOffset;
-  viewData[44 + 13] = heightOffset;
+  viewData[25] = 0;
   viewData[26] = -1;
-  viewData[124] = slopedShadow ? 1 : 0;
+  // Enable one real shadow cascade. Otherwise the stability falsifier sees
+  // only unshadowed texels (the old overlong readback supplied fake zeros).
   viewData[108] = 10;
-  if (slopedShadow) viewData[28 + 2] = 0.5;
+  viewData[124] = 1;
   viewData[228] = 0.1;
   viewData[229] = 10;
   viewData[230] = 0;
   viewData[235] = 1;
-  const paramsData = new Float32Array(32);
-  paramsData.set([-1, heightOffset - 1, 0.1, 0], 0);
-  paramsData.set([1, heightOffset + 1, 0.9, 0], 4);
-  paramsData.set([1, 1, 1, 0], 8);
+  const paramsData = new Float32Array(VOLUMETRIC_FOG_PARAMS_BYTES / 4);
+  paramsData.set([-1, -1, boundsMinZ, 0], 0);
+  paramsData.set([1, 1, boundsMaxZ, 0], 4);
+  paramsData.set([extinction, extinction, extinction, 0], 8);
   paramsData.set([1, 1, 1, 0], 12);
   paramsData.set([0, 0, 0, 0], 16);
-  paramsData.set([0, -1, 0, 0], 20);
+  paramsData.set([0, -1, 0, frameIndex], 20);
   paramsData.set([1, 1, 1, 0], 24);
-  paramsData.set([2, 0, 0, 0], 28);
-  paramsData[23] = frameIndex;
+  paramsData.set([maxDistance, 0, 0, 0], 28);
+  // `simulation.w` is the renderer-owned selected-sun cloud transmittance
+  // carrier. A fixture without a CloudLayer must retain the unshadowed
+  // #3197 baseline instead of reading the typed-array zero value.
+  paramsData[35] = 1;
   const lightData = new Uint8Array(CLUSTER_LIGHT_DATA_BYTES);
+  if (options.localLight !== undefined) {
+    paramsData[30] = options.localLight === 'point' ? 1 : 2;
+    const light = new Float32Array(lightData.buffer);
+    light.set([0, 0, 5.37, 0, 1, 1, 1, Math.cos(Math.PI / 8), 0, 0, -1, Math.cos(Math.PI / 6)]);
+    // Zero shadow intensity makes this a pure punctual-light integral. No
+    // projected image or shadow map can hide an undersampled light peak.
+    new Uint32Array(lightData.buffer).set(
+      [options.localLight === 'point' ? 0 : 1, 0xffffffff, 0xffffffff, 0xffffffff],
+      16,
+    );
+  }
+  for (let index = 0; index < owners; index++)
+    paramsData.set(paramsData.slice(0, 36), 36 * (index + 1));
+  paramsData[3] = owners;
+  if (options.secondDensity !== undefined || options.thinSeparated) {
+    for (let index = 0; index < owners; index++) paramsData[36 * (index + 1) + 7] = 1;
+  }
+  if (options.thinSeparated) {
+    paramsData[38] = 0.1;
+    paramsData[42] = 0.101;
+    paramsData[74] = 0.899;
+    paramsData[78] = 0.9;
+    for (const offset of [44, 80]) paramsData.set([100, 100, 100], offset);
+  }
+  if (options.reverse) {
+    const first = paramsData.slice(36, 72);
+    paramsData.copyWithin(36, 72, 108);
+    paramsData.set(first, 72);
+  }
   const clusterUniformData = new Float32Array(8);
   const clusterGrid = new Uint32Array(clusterUniformData.buffer);
   clusterGrid[0] = 1;
@@ -270,22 +471,12 @@ async function runInjectReadback(
   );
   if (!viewWrite.ok || !paramsWrite.ok || !lightDataWrite.ok || !clusterUniformWrite.ok)
     throw new Error('Dawn volume stage readback unavailable: uniform upload failed');
-  const densityData = new Uint8Array((BYTES_PER_PIXEL / 2) * SIZE * SIZE * SIZE);
-  for (let z = 0; z < SIZE; z++)
-    for (let y = 0; y < SIZE; y++)
-      for (let x = 0; x < SIZE; x++) {
-        const value =
-          densitySource === 'height-gradient'
-            ? Math.round((y / (SIZE - 1)) * 255)
-            : densitySource === 'depth-gradient'
-              ? Math.round((z / (SIZE - 1)) * 255)
-              : densitySource;
-        densityData.fill(
-          value,
-          ((z * SIZE + y) * SIZE + x) * 4,
-          ((z * SIZE + y) * SIZE + x + 1) * 4,
-        );
-      }
+  const densityData =
+    options.densityData ?? new Uint8Array((BYTES_PER_PIXEL / 2) * SIZE * SIZE * SIZE);
+  if (options.densityData === undefined) densityData.fill(densityByte);
+  if (densityData.length !== (BYTES_PER_PIXEL / 2) * SIZE * SIZE * SIZE) {
+    throw new Error(`Dawn volume stage readback density field length: ${densityData.length}`);
+  }
   const densityWrite = device.queue.writeTexture(
     { texture: densityTexture.value },
     densityData,
@@ -294,6 +485,13 @@ async function runInjectReadback(
   );
   if (!densityWrite.ok)
     throw new Error('Dawn volume stage readback unavailable: density upload failed');
+  const secondDensityWrite = device.queue.writeTexture(
+    { texture: secondDensityTexture.value },
+    new Uint8Array(densityData.length).fill(options.secondDensity ?? 255),
+    { offset: 0, bytesPerRow: SIZE * 4, rowsPerImage: SIZE },
+    { width: SIZE, height: SIZE, depthOrArrayLayers: SIZE },
+  );
+  if (!secondDensityWrite.ok) throw secondDensityWrite.error;
   const projectorWrite = device.queue.writeTexture(
     { texture: projectorTexture.value },
     new Uint8Array([255, 255, 255, 255]),
@@ -317,6 +515,7 @@ async function runInjectReadback(
       },
       { binding: 7, visibility: 4, buffer: { type: 'read-only-storage' } },
       { binding: 8, visibility: 4, buffer: { type: 'uniform' } },
+      { binding: 9, visibility: 4, texture: { sampleType: 'depth', viewDimension: '2d' } },
     ],
   });
   if (!layout.ok) throw layout.error;
@@ -383,6 +582,13 @@ async function runInjectReadback(
       { binding: 11, visibility: 4, buffer: { type: 'uniform' } },
       { binding: 12, visibility: 4, texture: { sampleType: 'float', viewDimension: '2d' } },
       { binding: 13, visibility: 4, sampler: { type: 'filtering' } },
+      { binding: 16, visibility: 4, texture: { sampleType: 'float', viewDimension: '2d' } },
+      { binding: 17, visibility: 4, sampler: { type: 'filtering' } },
+      ...Array.from({ length: 7 }, (_, index) => ({
+        binding: 18 + index,
+        visibility: 4,
+        texture: { sampleType: 'float' as const, viewDimension: '3d' as const },
+      })),
     ],
   });
   if (!temporalLayout.ok) throw temporalLayout.error;
@@ -421,6 +627,7 @@ async function runInjectReadback(
       { binding: 6, resource: { kind: 'textureView', value: outputView } },
       { binding: 7, resource: { kind: 'buffer', value: { buffer: lightDataBuffer.value } } },
       { binding: 8, resource: { kind: 'buffer', value: { buffer: clusterUniformBuffer.value } } },
+      { binding: 9, resource: { kind: 'textureView', value: shadowView.value } },
     ],
   });
   if (!bindings.ok) throw bindings.error;
@@ -443,7 +650,10 @@ async function runInjectReadback(
       { binding: 3, resource: { kind: 'buffer', value: { buffer: paramsBuffer.value } } },
       { binding: 4, resource: { kind: 'buffer', value: { buffer: viewBuffer.value } } },
       { binding: 5, resource: { kind: 'sampler', value: densitySampler.value } },
-      { binding: 6, resource: { kind: 'textureView', value: densityView } },
+      {
+        binding: 6,
+        resource: { kind: 'textureView', value: options.reverse ? secondDensityView : densityView },
+      },
       { binding: 7, resource: { kind: 'sampler', value: densitySampler.value } },
       { binding: 8, resource: { kind: 'textureView', value: historyView } },
       { binding: 9, resource: { kind: 'textureView', value: temporalView } },
@@ -451,6 +661,15 @@ async function runInjectReadback(
       { binding: 11, resource: { kind: 'buffer', value: { buffer: clusterUniformBuffer.value } } },
       { binding: 12, resource: { kind: 'textureView', value: projectorView } },
       { binding: 13, resource: { kind: 'sampler', value: densitySampler.value } },
+      { binding: 16, resource: { kind: 'textureView', value: projectorView } },
+      { binding: 17, resource: { kind: 'sampler', value: densitySampler.value } },
+      ...Array.from({ length: 7 }, (_, index) => ({
+        binding: 18 + index,
+        resource: {
+          kind: 'textureView' as const,
+          value: index === 0 && !options.reverse ? secondDensityView : densityView,
+        },
+      })),
     ],
   });
   if (!temporalBindings.ok) throw temporalBindings.error;
@@ -462,7 +681,7 @@ async function runInjectReadback(
       colorAttachments: [],
       depthStencilAttachment: {
         view,
-        depthClearValue: index === 0 ? sceneDepthClear : slopedShadow ? 0.5 : 1,
+        depthClearValue: index === 0 ? sceneDepthClear : shadowDepthClear,
         depthLoadOp: 'clear',
         depthStoreOp: 'store',
       },
@@ -472,12 +691,12 @@ async function runInjectReadback(
   const compute = encoder.value.beginComputePass();
   compute.setPipeline(pipeline.value);
   compute.setBindGroup(0, bindings.value);
-  compute.dispatchWorkgroups(1, 1, PACKED_LAYERS);
+  compute.dispatchWorkgroups(1, 1, PACKED_LAYERS * owners);
   compute.end();
   encoder.value.copyTextureToBuffer(
     { texture: outputTexture.value as never },
     { buffer: injectReadback.value as never, bytesPerRow: BYTES_PER_ROW, rowsPerImage: SIZE },
-    { width: SIZE, height: SIZE, depthOrArrayLayers: PACKED_LAYERS },
+    { width: SIZE, height: SIZE, depthOrArrayLayers: PACKED_LAYERS * owners },
   );
   const integrateCompute = encoder.value.beginComputePass();
   integrateCompute.setPipeline(integratePipeline.value);
@@ -537,28 +756,152 @@ async function runInjectReadback(
     return { red, green, alpha };
   };
   return {
-    inject: await decode(injectReadback.value, SIZE, 4, false),
+    inject: await decode(injectReadback.value, PACKED_LAYERS * owners, 4, false),
     temporal: await decode(temporalReadback.value, 1, BYTES_PER_PIXEL, true),
     integrate: await decode(integrateReadback.value, 1, BYTES_PER_PIXEL, true),
   };
 }
 
+// Independent radiative-transfer quadrature: a homogeneous medium and an
+// unshadowed punctual source. The near-light peak and spot cone make the old
+// 24 midpoint schedule visibly wrong even though its Beer transmittance passes.
+function punctualReference(kind: 'point' | 'spot', samples = 16_384): number[] {
+  const sigma = 0.01 * (2 * (128 / 255 + 0.5) ** 3 - 1);
+  return Array.from({ length: SIZE * SIZE }, (_, pixel) => {
+    const x = (((pixel % SIZE) + 0.5) / SIZE) * 2 - 1;
+    const y = 1 - ((Math.floor(pixel / SIZE) + 0.5) / SIZE) * 2;
+    const ds = 20 / samples;
+    let radiance = 0;
+    for (let i = 0; i < samples; i += 1) {
+      const s = (i + 0.5) * ds;
+      const z = 0.1 + s;
+      const distanceSquared = x * x + y * y + (5.37 - z) ** 2;
+      const cosine = (5.37 - z) / Math.sqrt(distanceSquared);
+      const t = Math.max(
+        0,
+        Math.min(
+          1,
+          (cosine - Math.cos(Math.PI / 6)) / (Math.cos(Math.PI / 8) - Math.cos(Math.PI / 6)),
+        ),
+      );
+      const cone = kind === 'point' ? 1 : t * t * (3 - 2 * t);
+      radiance += ((sigma * Math.exp(-sigma * s) * cone) / distanceSquared) * ds;
+    }
+    return radiance;
+  });
+}
+
 describe('volumetric fog production stage readback on Dawn', () => {
   it('keeps static shadow visibility stable across renderer frame phases', async () => {
-    const first = await runInjectReadback(1, 255, 0, 0, true);
-    const next = await runInjectReadback(1, 255, 0, 1, true);
+    const first = await runInjectReadback({ frameIndex: 0, shadowDepthClear: 0.5 });
+    const next = await runInjectReadback({ frameIndex: 1, shadowDepthClear: 0.5 });
+    expect(first.inject.red).toHaveLength(SIZE * SIZE * PACKED_LAYERS);
+    expect(first.inject).toEqual(next.inject);
     expect(first.inject.red.some((value) => value === 0)).toBe(true);
     expect(first.inject.red.some((value) => value > 0.9)).toBe(true);
-    expect(next.inject).toEqual(first.inject);
-  });
-  it('keeps a static depth-density field stable across renderer frame phases', async () => {
-    const first = await runInjectReadback(1, 'depth-gradient', 0, 0);
-    for (const frameIndex of [1, 7]) {
-      const next = await runInjectReadback(1, 'depth-gradient', 0, frameIndex);
-      expect(next.integrate.alpha).toEqual(first.integrate.alpha);
-      expect(next.integrate.red).toEqual(first.integrate.red);
-    }
-    expect(first.integrate.alpha[0]).toBeCloseTo(Math.exp(-0.4), 2);
+  });
+
+  it.each([
+    'point',
+    'spot',
+  ] as const)('resolves the %s light peak without coherent ray bands', async (localLight) => {
+    const reference = punctualReference(localLight);
+    const refined = punctualReference(localLight, 32_768);
+    expect(Math.max(...reference.map((v, i) => Math.abs(v - (refined[i] ?? 0)) / v))).toBeLessThan(
+      0.0001,
+    );
+    const options = {
+      localLight,
+      densityByte: 128,
+      extinction: 0.01,
+      boundsMaxZ: 20.1,
+      maxDistance: 20.1,
+      viewDepthScale: 21,
+    };
+    const maximumRelativeError = (values: VolumeStageReadbacks): number =>
+      Math.max(
+        ...values.integrate.red.map(
+          (v, i) => Math.abs(v - (reference[i] ?? 0)) / (reference[i] ?? 1),
+        ),
+      );
+    const production = await runInjectReadback(options);
+    const undersampled = await runInjectReadback({ ...options, integratorStepCount: 24 });
+    const resolved = await runInjectReadback({ ...options, integratorStepCount: 96 });
+    const refinedGpu = await runInjectReadback({ ...options, integratorStepCount: 384 });
+    const errors = {
+      refined: maximumRelativeError(refinedGpu),
+      production: maximumRelativeError(production),
+      undersampled: maximumRelativeError(undersampled),
+      resolved: maximumRelativeError(resolved),
+    };
+    // biome-ignore lint/suspicious/noConsole: production GPU spatial regression evidence.
+    console.info('[volumetric-fog-stage-readback] punctual-convergence', localLight, errors);
+    expect(errors.undersampled).toBeGreaterThan(0.1);
+    expect(errors.refined).toBeLessThan(0.003);
+    expect(errors.production).toBeLessThan(0.03);
+  });
+
+  it('retains fine density variation away from punctual light refinement', async () => {
+    // Matching end texels avoid an artificial discontinuity at the repeated
+    // texture seam. The interior stripes expose coarse-step density aliasing.
+    const field = createNonUniformDensityField([0, 255, 0, 255, 0, 255, 0, 0]);
+    const reference = nonUniformBeerReference(field, 0.05, 16_384, 0.1, 20.1);
+    const refined = nonUniformBeerReference(field, 0.05, 32_768, 0.1, 20.1);
+    expect(Math.abs(reference - refined)).toBeLessThan(0.0001);
+    const options = {
+      densityData: field.data,
+      extinction: 0.05,
+      boundsMaxZ: 20.1,
+      maxDistance: 20.1,
+      viewDepthScale: 21,
+    };
+    const production = firstStageValue(
+      (await runInjectReadback(options)).integrate.alpha,
+      'fine density',
+    );
+    const coarse = firstStageValue(
+      (await runInjectReadback({ ...options, integratorStepCount: 24 })).integrate.alpha,
+      'coarse density',
+    );
+    // biome-ignore lint/suspicious/noConsole: independent fine-density regression evidence.
+    console.info('[volumetric-fog-stage-readback] fine-density', { reference, production, coarse });
+    expect(Math.abs(coarse - reference)).toBeGreaterThan(0.005);
+    expect(Math.abs(production - reference)).toBeLessThan(0.002);
+  });
+
+  it('samples independent density textures and is invariant under owner permutation', async () => {
+    const transparent = await runInjectReadback({
+      sceneDepthClear: 0.57,
+      owners: 2,
+      secondDensity: 0,
+    });
+    const half = await runInjectReadback({ sceneDepthClear: 0.57, owners: 2, secondDensity: 128 });
+    const reversed = await runInjectReadback({
+      sceneDepthClear: 0.57,
+      owners: 2,
+      secondDensity: 128,
+      reverse: true,
+    });
+    expect(transparent.integrate.alpha[0]).toBeCloseTo(Math.exp(-0.47), 3);
+    expect(half.integrate.alpha[0]).toBeCloseTo(Math.exp(-0.47 * (1 + 128 / 255)), 3);
+    expect(reversed.integrate.alpha).toEqual(half.integrate.alpha);
+    expect(reversed.integrate.red).toEqual(half.integrate.red);
+  });
+  it('does not miss thin local volumes separated by empty space', async () => {
+    const values = await runInjectReadback({ owners: 2, thinSeparated: true });
+    expect(values.integrate.alpha[0]).toBeCloseTo(Math.exp(-0.002 * 100), 3);
+  });
+  it('adds overlapping optical depth instead of rejecting or selecting one volume', async () => {
+    const one = await runInjectReadback({ sceneDepthClear: 0.57 });
+    const two = await runInjectReadback({ sceneDepthClear: 0.57, owners: 2 });
+    const expected = Math.exp(-0.47 * (2 * 1.5 ** 3 - 1) * 2);
+    expect(two.integrate.alpha[0]).toBeCloseTo(expected, 3);
+    expect(two.integrate.alpha[0]).toBeLessThan(one.integrate.alpha[0] ?? 0);
+    expect(two.integrate.red[0]).toBeGreaterThan(one.integrate.red[0] ?? 0);
+  });
+  it('integrates all eight admitted owners through the production parameter layout', async () => {
+    const values = await runInjectReadback({ sceneDepthClear: 0.57, owners: 8, extinction: 0.1 });
+    expect(values.integrate.alpha[0]).toBeCloseTo(Math.exp(-0.47 * (2 * 1.5 ** 3 - 1) * 0.8), 3);
   });
   it('injects raw density then resolves a 2d integrated volume', async () => {
     const values = await runInjectReadback();
@@ -580,23 +923,170 @@ describe('volumetric fog production stage readback on Dawn', () => {
   });
 
   it('clips the final ray step to the scene-depth segment', async () => {
-    const values = await runInjectReadback(0.57);
+    const values = await runInjectReadback({ sceneDepthClear: 0.57 });
     const transmittance = values.integrate.alpha[0];
-    // White encodes density one; integrate only the visible 0.47-unit segment.
-    expect(transmittance).toBeCloseTo(Math.exp(-0.47), 2);
+    // The fixture uploads an all-white source texture. The authored Three
+    // smoke expression therefore evaluates to 2 * 1.5^3 - 1 = 5.75 before
+    // Beer-Lambert consumes it; only the final 0.47-unit segment is allowed
+    // to contribute after the scene-depth clip.
+    const sourceDensity = 2 * 1.5 ** 3 - 1;
+    expect(transmittance).toBeCloseTo(Math.exp(-0.47 * sourceDensity), 2);
     expect(values.integrate.red[0]).toBeGreaterThan(0);
   });
-  it.each([0, 64, 128])('preserves authored uniform density %s/255', async (densityByte) => {
-    const values = await runInjectReadback(0.57, densityByte);
-    expect(values.integrate.alpha[0]).toBeCloseTo(Math.exp((-0.47 * densityByte) / 255), 2);
-    if (densityByte === 0) expect(values.integrate.red.every((value) => value === 0)).toBe(true);
+
+  it('keeps a zero medium transparent and applies Beer-Lambert monotonically', async () => {
+    const empty = await runInjectReadback({ densityByte: 0 });
+    const medium = await runInjectReadback({ densityByte: 128 });
+    const dense = await runInjectReadback({ densityByte: 255 });
+    const emptyScattering = firstStageValue(empty.integrate.red, 'empty scattering');
+    const denseScattering = firstStageValue(dense.integrate.red, 'dense scattering');
+    const mediumScattering = firstStageValue(medium.integrate.red, 'medium scattering');
+    const emptyTransmission = firstStageValue(empty.integrate.alpha, 'empty transmission');
+    const mediumTransmission = firstStageValue(medium.integrate.alpha, 'medium transmission');
+    const denseTransmission = firstStageValue(dense.integrate.alpha, 'dense transmission');
+    expect(emptyScattering).toBeCloseTo(0, 2);
+    expect(emptyTransmission).toBeCloseTo(1, 2);
+    expect(denseTransmission).toBeLessThan(mediumTransmission);
+    expect(mediumTransmission).toBeLessThan(emptyTransmission);
+    expect(denseScattering).toBeGreaterThan(mediumScattering);
   });
 
-  it.each([
-    0, 20,
-  ])('maps height density through world bounds translated by %s', async (heightOffset) => {
-    const values = await runInjectReadback(0.57, 'height-gradient', heightOffset);
-    expect(values.integrate.alpha[0]).toBeCloseTo(Math.exp(-0.47), 2);
-    expect(values.integrate.alpha[(SIZE - 1) * SIZE]).toBeCloseTo(1, 3);
+  it('keeps extinction monotonic and bounds temporal jitter spread', async () => {
+    const lowExtinction = await runInjectReadback({ densityByte: 128, extinction: 0.25 });
+    const highExtinction = await runInjectReadback({ densityByte: 128, extinction: 1 });
+    const lowTransmission = firstStageValue(lowExtinction.integrate.alpha, 'low extinction');
+    const highTransmission = firstStageValue(highExtinction.integrate.alpha, 'high extinction');
+    expect(highTransmission).toBeLessThan(lowTransmission);
+
+    const samples: number[] = [];
+    for (let frameIndex = 0; frameIndex < 4; frameIndex += 1) {
+      const value = await runInjectReadback({ densityByte: 128, frameIndex });
+      const transmission = firstStageValue(value.integrate.alpha, `frame ${frameIndex}`);
+      expect(Number.isFinite(transmission)).toBe(true);
+      samples.push(transmission);
+    }
+    const spread = Math.max(...samples) - Math.min(...samples);
+    // Frame ordinals must not change a fixed World-time density integral.
+    // This remains separate from continuous-frame history and spatial accuracy.
+    expect(spread).toBeLessThan(0.2);
+  });
+
+  it('converges production step-count variants to the homogeneous Beer oracle', async () => {
+    const sceneDepthClear = 0.57;
+    const sourceDensity = 2 * 1.5 ** 3 - 1;
+    const oracle = Math.exp(-0.47 * sourceDensity);
+    const transmissions = await Promise.all(
+      [6, 12, 24].map(async (integratorStepCount) => {
+        const values = await runInjectReadback({
+          sceneDepthClear,
+          integratorStepCount,
+        });
+        return firstStageValue(values.integrate.alpha, `${integratorStepCount}-step transmission`);
+      }),
+    );
+    for (const transmission of transmissions) {
+      expect(transmission).toBeCloseTo(oracle, 2);
+    }
+    expect(Math.max(...transmissions) - Math.min(...transmissions)).toBeLessThan(0.01);
+  });
+
+  it('converges production steps against an independent non-uniform Beer reference', async () => {
+    const field = createNonUniformDensityField();
+    const flattenedField = createFlattenedDensityField(field);
+    const reference = nonUniformBeerReference(
+      field,
+      NON_UNIFORM_EXTINCTION,
+      16_384,
+      VOLUME_BOUNDS_MIN_Z,
+      NON_UNIFORM_BOUNDS_MAX_Z,
+    );
+    const refinedReference = nonUniformBeerReference(
+      field,
+      NON_UNIFORM_EXTINCTION,
+      32_768,
+      VOLUME_BOUNDS_MIN_Z,
+      NON_UNIFORM_BOUNDS_MAX_Z,
+    );
+    const flattenedReference = nonUniformBeerReference(
+      flattenedField,
+      NON_UNIFORM_EXTINCTION,
+      16_384,
+      VOLUME_BOUNDS_MIN_Z,
+      NON_UNIFORM_BOUNDS_MAX_Z,
+    );
+    expect(Math.abs(reference - refinedReference)).toBeLessThan(MAX_NON_UNIFORM_BEER_ERROR / 10);
+    expect(Math.abs(reference - flattenedReference)).toBeGreaterThan(
+      MIN_NON_UNIFORM_REFERENCE_SEPARATION,
+    );
+    const stepCounts = [24, 48, 96] as const;
+    const transmissions = await Promise.all(
+      stepCounts.map(async (integratorStepCount) => {
+        const values = await runInjectReadback({
+          boundsMaxZ: NON_UNIFORM_BOUNDS_MAX_Z,
+          densityData: field.data,
+          extinction: NON_UNIFORM_EXTINCTION,
+          integratorStepCount,
+          maxDistance: NON_UNIFORM_BOUNDS_MAX_Z,
+          viewDepthScale: 10,
+        });
+        return firstStageValue(
+          values.integrate.alpha,
+          `${integratorStepCount}-step non-uniform transmission`,
+        );
+      }),
+    );
+    const flattenedValues = await runInjectReadback({
+      boundsMaxZ: NON_UNIFORM_BOUNDS_MAX_Z,
+      densityData: flattenedField.data,
+      extinction: NON_UNIFORM_EXTINCTION,
+      integratorStepCount: 96,
+      maxDistance: NON_UNIFORM_BOUNDS_MAX_Z,
+      viewDepthScale: 10,
+    });
+    const flattenedTransmission = firstStageValue(
+      flattenedValues.integrate.alpha,
+      'flattened-field transmission',
+    );
+    const defaultValues = await runInjectReadback({
+      boundsMaxZ: NON_UNIFORM_BOUNDS_MAX_Z,
+      densityData: field.data,
+      extinction: NON_UNIFORM_EXTINCTION,
+      maxDistance: NON_UNIFORM_BOUNDS_MAX_Z,
+      viewDepthScale: 10,
+    });
+    const defaultTransmission = firstStageValue(
+      defaultValues.integrate.alpha,
+      'production transmission',
+    );
+    const errors = transmissions.map((transmission) => Math.abs(transmission - reference));
+    const flattenedError = Math.abs(flattenedTransmission - flattenedReference);
+    const defaultError = Math.abs(defaultTransmission - reference);
+    // biome-ignore lint/suspicious/noConsole: non-uniform production convergence receipt.
+    console.info(
+      '[volumetric-fog-stage-readback] non-uniform-convergence',
+      JSON.stringify({
+        reference,
+        refinedReference,
+        flattenedReference,
+        stepCounts,
+        transmissions,
+        errors,
+        flattenedTransmission,
+        flattenedError,
+        defaultTransmission,
+        defaultError,
+      }),
+    );
+    for (const error of errors) expect(error).toBeLessThan(MAX_NON_UNIFORM_BEER_ERROR);
+    expect(flattenedError).toBeLessThan(MAX_NON_UNIFORM_BEER_ERROR);
+    expect(defaultError).toBeLessThan(MAX_NON_UNIFORM_BEER_ERROR);
+    expect(Math.abs((transmissions[2] ?? NaN) - flattenedTransmission)).toBeGreaterThan(
+      MIN_NON_UNIFORM_GPU_SEPARATION,
+    );
+    const spread = Math.max(...transmissions) - Math.min(...transmissions);
+    // rgba16float readback quantizes nearby step variants onto the same value,
+    // so strict error ordering is not a stable production contract. Keep the
+    // independent reference and require a bounded cross-step spread instead.
+    expect(spread).toBeLessThan(MAX_NON_UNIFORM_BEER_ERROR);
   });
 });