@forgeax/engine-render 0.1.33 → 0.1.35

package/src/assembly/webgpu-vertex-layouts.ts

@@ -253,7 +253,7 @@ export function resolveWebGPUVertexBufferLayouts(options: {
                         : undefined,
                     ),
                   )
-                : layoutKind === 'pbr-skin'
+                : layoutKind === 'pbr-skin' || layoutKind === 'gpu-driven-cluster-skin'
                   ? toGpuVertexBufferLayouts(
                       deriveVertexBufferLayout(
                         meshAttributes ?? SKIN_VERTEX_ATTRIBUTE_MAP,

package/src/barrel-distortion.ts

@@ -0,0 +1,247 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import {
+  type BarrelDistortionData,
+  validateBarrelDistortionParameters,
+} from './components/barrel-distortion';
+import { BarrelDistortionInvalidParameterError } from './errors/render';
+
+/** One immutable mapping used by the output pass and display interaction. */
+export interface BarrelDistortionMapping {
+  readonly width: number;
+  readonly height: number;
+  readonly aspect: number;
+  readonly strength: number;
+  readonly centerX: number;
+  readonly centerY: number;
+  readonly radiusSquared: number;
+  /** Unjittered camera facts from the submitted frame, when available. */
+  readonly camera?: BarrelDistortionCameraFrame;
+}
+
+/** Camera matrices paired with the mapping's accepted render frame. */
+export interface BarrelDistortionCameraFrame {
+  readonly projection: 'perspective' | 'orthographic';
+  /** Far plane from the same submitted camera snapshot as the matrices. */
+  readonly far: number;
+  readonly viewMatrix: ArrayLike<number>;
+  readonly projectionMatrix: ArrayLike<number>;
+}
+
+// The equations below are evaluated in JavaScript's binary64 domain. Keep the
+// public input domain strict, then absorb only a handful of binary64 ulps at
+// the computed UV boundary. A real crop miss is orders of magnitude larger
+// and remains rejected.
+const COMPUTED_UV_BOUNDARY_EPSILON = Number.EPSILON * 16;
+
+/**
+ * Detach and deep-freeze a mapping before it crosses a public or realm
+ * boundary. Worker structured cloning drops the source object's frozen state,
+ * so every receiving boundary must call this helper again.
+ */
+export function freezeBarrelDistortionMapping(
+  mapping: BarrelDistortionMapping,
+): BarrelDistortionMapping {
+  const camera = mapping.camera;
+  return Object.freeze({
+    ...mapping,
+    ...(camera === undefined
+      ? {}
+      : {
+          camera: Object.freeze({
+            projection: camera.projection,
+            far: camera.far,
+            viewMatrix: Object.freeze(Array.from(camera.viewMatrix)),
+            projectionMatrix: Object.freeze(Array.from(camera.projectionMatrix)),
+          }),
+        }),
+  });
+}
+
+/** Attach the unjittered camera facts at the queue-submit publication boundary. */
+export function attachBarrelDistortionCameraFrame(
+  mapping: BarrelDistortionMapping,
+  camera: BarrelDistortionCameraFrame,
+): BarrelDistortionMapping {
+  return freezeBarrelDistortionMapping({
+    ...mapping,
+    camera: {
+      projection: camera.projection,
+      far: camera.far,
+      viewMatrix: camera.viewMatrix,
+      projectionMatrix: camera.projectionMatrix,
+    },
+  });
+}
+
+/** Continuous output-viewport pixel coordinate. */
+export interface DisplayPoint {
+  x: number;
+  y: number;
+}
+
+function invalidExtent(
+  field: 'width' | 'height',
+  value: number,
+): BarrelDistortionInvalidParameterError {
+  return new BarrelDistortionInvalidParameterError({
+    field,
+    value,
+    expected: 'finite and greater than 0',
+  });
+}
+
+/** Derive the output-sized mapping, including the auto-crop normalization. */
+export function createBarrelDistortionMapping(
+  width: number,
+  height: number,
+  input: Partial<BarrelDistortionData> | undefined,
+): Result<BarrelDistortionMapping, BarrelDistortionInvalidParameterError> {
+  if (!Number.isFinite(width) || width <= 0) return err(invalidExtent('width', width));
+  if (!Number.isFinite(height) || height <= 0) return err(invalidExtent('height', height));
+  const parameters = validateBarrelDistortionParameters(input);
+  if (!parameters.ok) return parameters;
+  const { strength, centerX, centerY } = parameters.value;
+  const aspect = width / height;
+  const radiusSquared =
+    4 *
+    (aspect * aspect * Math.max(centerX, 1 - centerX) ** 2 + Math.max(centerY, 1 - centerY) ** 2);
+  return ok(
+    Object.freeze({
+      width,
+      height,
+      aspect,
+      strength,
+      centerX,
+      centerY,
+      radiusSquared,
+    }),
+  );
+}
+
+function displayToSceneScale(mapping: BarrelDistortionMapping, ux: number, uy: number): number {
+  const px = 2 * mapping.aspect * (ux - mapping.centerX);
+  const py = 2 * (uy - mapping.centerY);
+  const t = (px * px + py * py) / mapping.radiusSquared;
+  return (1 - mapping.strength) / (1 - mapping.strength * t);
+}
+
+/**
+ * Accept a computed UV only when it is inside the unit interval or within a
+ * machine-precision boundary. Inputs are checked before the equation runs;
+ * this helper must never turn an out-of-domain caller input into a valid UV.
+ */
+function normalizeComputedUv(out: DisplayPoint, x: number, y: number): boolean {
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return false;
+  if (
+    x < -COMPUTED_UV_BOUNDARY_EPSILON ||
+    x > 1 + COMPUTED_UV_BOUNDARY_EPSILON ||
+    y < -COMPUTED_UV_BOUNDARY_EPSILON ||
+    y > 1 + COMPUTED_UV_BOUNDARY_EPSILON
+  ) {
+    return false;
+  }
+  out.x = Math.min(1, Math.max(0, x));
+  out.y = Math.min(1, Math.max(0, y));
+  return true;
+}
+
+/** Shared display UV -> source UV equation used by the GPU and CPU paths. */
+export function mapDisplayUvToSceneUv(
+  out: DisplayPoint,
+  mapping: BarrelDistortionMapping,
+  ux: number,
+  uy: number,
+): boolean {
+  if (!Number.isFinite(ux) || !Number.isFinite(uy) || ux < 0 || ux > 1 || uy < 0 || uy > 1)
+    return false;
+  if (mapping.strength === 0) {
+    out.x = ux;
+    out.y = uy;
+    return ux >= 0 && ux <= 1 && uy >= 0 && uy <= 1;
+  }
+  const scale = displayToSceneScale(mapping, ux, uy);
+  return normalizeComputedUv(
+    out,
+    mapping.centerX + (ux - mapping.centerX) * scale,
+    mapping.centerY + (uy - mapping.centerY) * scale,
+  );
+}
+
+/** Analytic source UV -> display UV inverse of the shared barrel model. */
+export function mapSceneUvToDisplayUv(
+  out: DisplayPoint,
+  mapping: BarrelDistortionMapping,
+  ux: number,
+  uy: number,
+): boolean {
+  if (!Number.isFinite(ux) || !Number.isFinite(uy) || ux < 0 || ux > 1 || uy < 0 || uy > 1)
+    return false;
+  if (mapping.strength === 0) {
+    out.x = ux;
+    out.y = uy;
+    return ux >= 0 && ux <= 1 && uy >= 0 && uy <= 1;
+  }
+  const px = 2 * mapping.aspect * (ux - mapping.centerX);
+  const py = 2 * (uy - mapping.centerY);
+  const sourceRadius = Math.hypot(px, py);
+  if (sourceRadius === 0) {
+    out.x = mapping.centerX;
+    out.y = mapping.centerY;
+    return true;
+  }
+  const discriminant =
+    (1 - mapping.strength) ** 2 +
+    (4 * mapping.strength * sourceRadius * sourceRadius) / mapping.radiusSquared;
+  const displayRadius =
+    (2 * sourceRadius) / (1 - mapping.strength + Math.sqrt(Math.max(0, discriminant)));
+  const scale = displayRadius / sourceRadius;
+  return normalizeComputedUv(
+    out,
+    mapping.centerX + (ux - mapping.centerX) * scale,
+    mapping.centerY + (uy - mapping.centerY) * scale,
+  );
+}
+
+function validPixel(point: DisplayPoint): boolean {
+  return Number.isFinite(point.x) && Number.isFinite(point.y);
+}
+
+/** Map an output display pixel to the unwarped scene pixel. */
+export function mapDisplayToScene(
+  out: DisplayPoint,
+  mapping: BarrelDistortionMapping,
+  displayX: number,
+  displayY: number,
+): boolean {
+  if (!Number.isFinite(displayX) || !Number.isFinite(displayY)) return false;
+  if (displayX < 0 || displayX > mapping.width || displayY < 0 || displayY > mapping.height) {
+    return false;
+  }
+  const scene = { x: 0, y: 0 };
+  if (!mapDisplayUvToSceneUv(scene, mapping, displayX / mapping.width, displayY / mapping.height)) {
+    return false;
+  }
+  out.x = scene.x * mapping.width;
+  out.y = scene.y * mapping.height;
+  return validPixel(out);
+}
+
+/** Map an unwarped scene pixel to its visible output display pixel. */
+export function mapSceneToDisplay(
+  out: DisplayPoint,
+  mapping: BarrelDistortionMapping,
+  sceneX: number,
+  sceneY: number,
+): boolean {
+  if (!Number.isFinite(sceneX) || !Number.isFinite(sceneY)) return false;
+  if (sceneX < 0 || sceneX > mapping.width || sceneY < 0 || sceneY > mapping.height) {
+    return false;
+  }
+  const display = { x: 0, y: 0 };
+  if (!mapSceneUvToDisplayUv(display, mapping, sceneX / mapping.width, sceneY / mapping.height)) {
+    return false;
+  }
+  out.x = display.x * mapping.width;
+  out.y = display.y * mapping.height;
+  return validPixel(out);
+}

package/src/cloud/__tests__/cloud-density-parity.dawn.test.ts

@@ -0,0 +1,173 @@
+/// <reference types="@webgpu/types" />
+
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { evaluateCloudDensity } from '../density';
+import { CLOUD_VIEW_FULLSCREEN_WGSL } from '../feature';
+import { cloudIncidentLight } from '../optics';
+import { validateCloudLayer } from '../parameters';
+
+// Execute both production WGSL definitions. A source-text comparison cannot
+// detect a hash constant mismatch or a different body/envelope interpretation.
+describe('cloud density CPU/GPU parity', () => {
+  it('uses the same formation and density in cached-field generation and both analytic shaders', async () => {
+    const adapter = await navigator.gpu.requestAdapter();
+    expect(adapter).not.toBeNull();
+    if (!adapter) throw new Error('WebGPU adapter unavailable');
+    const device = await adapter.requestDevice();
+    const params = validateCloudLayer({
+      baseHeight: 0,
+      thickness: 1,
+      scale: 1,
+      seed: 42,
+      coverage: 0.8,
+      density: 1,
+      wind: [0, 0, 0],
+    });
+    if (!params.ok) throw params.error;
+    const shared = readFileSync(
+      new URL('../../../../shader/src/cloud.wgsl', import.meta.url),
+      'utf8',
+    );
+    try {
+      for (const source of [CLOUD_VIEW_FULLSCREEN_WGSL, shared]) {
+        const helpers = source.slice(
+          source.indexOf('fn cloud_hash3('),
+          source.indexOf(source === shared ? 'fn cloud_density(' : 'fn cloud_analytic_density('),
+        );
+        const code = `
+          const CLOUD_VERTICAL_NOISE_CELLS: f32 = 2.0;
+          ${helpers}
+          @group(0) @binding(0) var<storage, read_write> output: array<f32>;
+          @compute @workgroup_size(64)
+          fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+            let p = vec3<f32>(f32(id.x % 13u) / 13.0, (f32(id.x % 11u) + 0.5) / 11.0, f32(id.x % 17u) / 17.0);
+            output[id.x] = cloud_compose_density(p.y, cloud_formation_field(p, 42u), 0.8);
+          }`;
+        const module = device.createShaderModule({ code });
+        const info = await module.getCompilationInfo();
+        expect(info.messages.filter((message) => message.type === 'error')).toEqual([]);
+        const pipeline = await device.createComputePipelineAsync({
+          layout: 'auto',
+          compute: { module, entryPoint: 'main' },
+        });
+        const output = device.createBuffer({
+          size: 512,
+          usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+        });
+        const readback = device.createBuffer({
+          size: 512,
+          usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+        });
+        try {
+          const encoder = device.createCommandEncoder();
+          const pass = encoder.beginComputePass();
+          pass.setPipeline(pipeline);
+          pass.setBindGroup(
+            0,
+            device.createBindGroup({
+              layout: pipeline.getBindGroupLayout(0),
+              entries: [{ binding: 0, resource: { buffer: output } }],
+            }),
+          );
+          pass.dispatchWorkgroups(2);
+          pass.end();
+          encoder.copyBufferToBuffer(output, 0, readback, 0, 512);
+          device.queue.submit([encoder.finish()]);
+          await readback.mapAsync(GPUMapMode.READ);
+          const values = new Float32Array(readback.getMappedRange());
+          let maxError = 0;
+          for (let i = 0; i < 128; i++) {
+            const point = [(i % 13) / 13, ((i % 11) + 0.5) / 11, (i % 17) / 17];
+            maxError = Math.max(
+              maxError,
+              Math.abs(
+                (values[i] ?? Number.NaN) - evaluateCloudDensity(params.value, point).density,
+              ),
+            );
+          }
+          expect(maxError).toBeLessThan(0.001);
+          readback.unmap();
+        } finally {
+          output.destroy();
+          readback.destroy();
+        }
+      }
+    } finally {
+      device.destroy();
+    }
+  });
+});
+
+describe('cloud incident light CPU/GPU parity', () => {
+  it('uses the volume light basis and the same phase and fill in the CPU oracle', async () => {
+    const adapter = await navigator.gpu.requestAdapter();
+    if (!adapter) throw new Error('WebGPU adapter unavailable');
+    const device = await adapter.requestDevice();
+    const output = device.createBuffer({
+      size: 1024,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+    });
+    const readback = device.createBuffer({
+      size: 1024,
+      usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+    });
+    try {
+      const helpers = CLOUD_VIEW_FULLSCREEN_WGSL.slice(
+        CLOUD_VIEW_FULLSCREEN_WGSL.indexOf('fn cloud_henyey_greenstein('),
+        CLOUD_VIEW_FULLSCREEN_WGSL.indexOf('fn cloud_ray_jitter('),
+      );
+      const module = device.createShaderModule({
+        code: `
+        struct Light { sunRadiance: vec4<f32> };
+        var<private> cloud: Light = Light(vec4<f32>(1.0));
+        ${helpers}
+        @group(0) @binding(0) var<storage, read_write> output: array<vec4<f32>>;
+        @compute @workgroup_size(64)
+        fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+          let t = f32(id.x % 8u) / 7.0;
+          let angle = f32((id.x / 8u) % 4u) / 1.5 - 1.0;
+          let height = f32(id.x / 32u);
+          output[id.x] = vec4<f32>(cloud_incident_light(t, angle, height), 1.0);
+        }`,
+      });
+      const pipeline = await device.createComputePipelineAsync({
+        layout: 'auto',
+        compute: { module, entryPoint: 'main' },
+      });
+      const encoder = device.createCommandEncoder();
+      const pass = encoder.beginComputePass();
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(
+        0,
+        device.createBindGroup({
+          layout: pipeline.getBindGroupLayout(0),
+          entries: [{ binding: 0, resource: { buffer: output } }],
+        }),
+      );
+      pass.dispatchWorkgroups(1);
+      pass.end();
+      encoder.copyBufferToBuffer(output, 0, readback, 0, 1024);
+      device.queue.submit([encoder.finish()]);
+      await readback.mapAsync(GPUMapMode.READ);
+      const values = new Float32Array(readback.getMappedRange());
+      for (let i = 0; i < 64; i++) {
+        const expected = cloudIncidentLight(
+          (i % 8) / 7,
+          (Math.floor(i / 8) % 4) / 1.5 - 1,
+          Math.floor(i / 32),
+        );
+        for (const channel of [0, 1, 2] as const)
+          expect(values[i * 4 + channel]).toBeCloseTo(expected[channel], 4);
+      }
+      readback.unmap();
+      // An unoccluded sideways ray must retain direct and multiple scattering
+      // in the shared light units; an accidental extra 1/(4*pi) dims this badly.
+      expect(cloudIncidentLight(1, 0, 1)[0]).toBeGreaterThan(1);
+    } finally {
+      output.destroy();
+      readback.destroy();
+      device.destroy();
+    }
+  });
+});

package/src/cloud/__tests__/cloud-layer-framebuffer-y.dawn.test.ts

@@ -0,0 +1,265 @@
+import { describe, expect, it } from 'vitest';
+import { VIEW_UNIFORM_BYTES } from '../../record/view-ubo';
+import {
+  CLOUD_HISTORY_FULLSCREEN_WGSL,
+  CLOUD_VIEW_FULLSCREEN_WGSL,
+  CLOUD_VIEW_PARAMS_BYTES,
+} from '../feature';
+
+const WIDTH = 4;
+const HEIGHT = 4;
+const TEXTURE_BINDING = 0x04;
+const RENDER_ATTACHMENT = 0x10;
+const COPY_SRC = 0x01;
+const COPY_DST = 0x02;
+const MAP_READ = 0x0001;
+const BUFFER_COPY_DST = 0x0008;
+const STORAGE = 0x0080;
+const UNIFORM = 0x0040;
+const MAP_MODE_READ = 0x0001;
+
+interface Readback {
+  readonly rows: readonly number[];
+  readonly center: number;
+}
+
+function identity(target: Float32Array, offset: number): void {
+  target[offset] = 1;
+  target[offset + 5] = 1;
+  target[offset + 10] = 1;
+  target[offset + 15] = 1;
+}
+
+function createSource(device: GPUDevice): GPUTexture {
+  const texture = device.createTexture({
+    size: [WIDTH, HEIGHT],
+    format: 'rgba8unorm',
+    usage: TEXTURE_BINDING | COPY_DST,
+  });
+  const bytes = new Uint8Array(WIDTH * HEIGHT * 4);
+  for (let y = 0; y < HEIGHT; y += 1) {
+    for (let x = 0; x < WIDTH; x += 1) {
+      const offset = (y * WIDTH + x) * 4;
+      bytes[offset] = 20 + y * 60;
+      bytes[offset + 1] = 7 + x * 31;
+      bytes[offset + 2] = 240 - y * 40;
+      bytes[offset + 3] = 255;
+    }
+  }
+  device.queue.writeTexture(
+    { texture },
+    bytes,
+    { bytesPerRow: WIDTH * 4 },
+    { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+  );
+  return texture;
+}
+
+function createDepth(device: GPUDevice): GPUTexture {
+  return device.createTexture({
+    size: [WIDTH, HEIGHT],
+    format: 'depth32float',
+    usage: TEXTURE_BINDING | RENDER_ATTACHMENT,
+  });
+}
+
+function createViewUniforms(): Float32Array {
+  const data = new Float32Array(VIEW_UNIFORM_BYTES / Float32Array.BYTES_PER_ELEMENT);
+  identity(data, 0);
+  identity(data, 44);
+  data[16] = 0;
+  data[17] = -1;
+  data[18] = 0;
+  data[20] = 1;
+  data[21] = 1;
+  data[22] = 1;
+  data[24] = 0;
+  data[25] = 0;
+  data[26] = 0;
+  return data;
+}
+
+function createCloudUniforms(density: number): Float32Array {
+  const data = new Float32Array(24);
+  data[0] = -1;
+  data[1] = 2;
+  data[2] = 1;
+  data[3] = density;
+  data[4] = 1;
+  data[5] = 0;
+  data[6] = 10;
+  data[7] = 7;
+  data[8] = 0;
+  data[9] = 0;
+  data[10] = 0;
+  data[12] = 0;
+  data[13] = -1;
+  data[14] = 0;
+  data[16] = 1;
+  data[17] = 1;
+  data[18] = 1;
+  const integers = new Uint32Array(data.buffer);
+  integers[20] = 4;
+  integers[21] = 8;
+  integers[22] = 8;
+  return data;
+}
+
+async function render(
+  device: GPUDevice,
+  pipeline: GPURenderPipeline,
+  depthValue: number,
+  density: number,
+): Promise<Readback> {
+  const source = createSource(device);
+  const depth = createDepth(device);
+  const output = device.createTexture({
+    size: [WIDTH, HEIGHT],
+    format: 'rgba8unorm',
+    usage: RENDER_ATTACHMENT | COPY_SRC,
+  });
+  const viewBuffer = device.createBuffer({
+    size: VIEW_UNIFORM_BYTES,
+    usage: UNIFORM | BUFFER_COPY_DST,
+  });
+  const cloudBuffer = device.createBuffer({
+    size: CLOUD_VIEW_PARAMS_BYTES,
+    usage: UNIFORM | BUFFER_COPY_DST,
+  });
+  // The production cache contains three R8 formation planes (weather, body,
+  // erosion), packed into 48 u32 lanes for the 4^3 fixture. Keep the Dawn
+  // fixture on the same storage extent so the density shader never reads
+  // beyond the test resource when the cloud is enabled.
+  const densityBuffer = device.createBuffer({ size: 192, usage: STORAGE | BUFFER_COPY_DST });
+  const previousRadiance = device.createTexture({
+    size: [WIDTH, HEIGHT],
+    format: 'rgba16float',
+    usage: TEXTURE_BINDING | RENDER_ATTACHMENT,
+  });
+  const previousTransmittance = device.createTexture({
+    size: [WIDTH, HEIGHT],
+    format: 'rgba16float',
+    usage: TEXTURE_BINDING | RENDER_ATTACHMENT,
+  });
+  const previousDepth = device.createTexture({
+    size: [WIDTH, HEIGHT],
+    format: 'rgba16float',
+    usage: TEXTURE_BINDING | RENDER_ATTACHMENT,
+  });
+  const readback = device.createBuffer({
+    size: 256 * HEIGHT,
+    usage: MAP_READ | BUFFER_COPY_DST,
+  });
+  device.queue.writeBuffer(viewBuffer, 0, createViewUniforms());
+  device.queue.writeBuffer(cloudBuffer, 0, createCloudUniforms(density));
+  device.queue.writeBuffer(
+    densityBuffer,
+    0,
+    new Uint32Array(48).fill(density === 0 ? 0 : 0xffffffff),
+  );
+  const group0 = device.createBindGroup({
+    layout: pipeline.getBindGroupLayout(0),
+    entries: [{ binding: 0, resource: { buffer: viewBuffer } }],
+  });
+  const group1 = device.createBindGroup({
+    layout: pipeline.getBindGroupLayout(1),
+    entries: [
+      { binding: 0, resource: source.createView() },
+      { binding: 1, resource: device.createSampler() },
+      { binding: 2, resource: { buffer: cloudBuffer } },
+      { binding: 3, resource: depth.createView() },
+      { binding: 4, resource: device.createSampler() },
+      { binding: 5, resource: previousRadiance.createView() },
+      { binding: 6, resource: previousTransmittance.createView() },
+      { binding: 7, resource: previousDepth.createView() },
+      { binding: 8, resource: { buffer: densityBuffer } },
+    ],
+  });
+  const encoder = device.createCommandEncoder();
+  const depthPass = encoder.beginRenderPass({
+    colorAttachments: [],
+    depthStencilAttachment: {
+      view: depth.createView(),
+      depthClearValue: depthValue,
+      depthLoadOp: 'clear',
+      depthStoreOp: 'store',
+    },
+  });
+  depthPass.end();
+  const pass = encoder.beginRenderPass({
+    colorAttachments: [
+      {
+        view: output.createView(),
+        clearValue: [0, 0, 0, 1],
+        loadOp: 'clear',
+        storeOp: 'store',
+      },
+    ],
+  });
+  pass.setPipeline(pipeline);
+  pass.setBindGroup(0, group0);
+  pass.setBindGroup(1, group1);
+  pass.draw(3);
+  pass.end();
+  encoder.copyTextureToBuffer(
+    { texture: output },
+    { buffer: readback, bytesPerRow: 256, rowsPerImage: HEIGHT },
+    { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+  );
+  device.queue.submit([encoder.finish()]);
+  await device.queue.onSubmittedWorkDone();
+  await readback.mapAsync(MAP_MODE_READ);
+  const bytes = new Uint8Array(readback.getMappedRange().slice(0));
+  readback.unmap();
+  source.destroy();
+  depth.destroy();
+  output.destroy();
+  viewBuffer.destroy();
+  cloudBuffer.destroy();
+  densityBuffer.destroy();
+  previousRadiance.destroy();
+  previousTransmittance.destroy();
+  previousDepth.destroy();
+  readback.destroy();
+  return {
+    rows: Array.from({ length: HEIGHT }, (_, y) => bytes[y * 256] ?? 0),
+    center: bytes[(HEIGHT >> 1) * 256 + (WIDTH >> 1) * 4] ?? 0,
+  };
+}
+
+describe('CloudLayer framebuffer Y convention on Dawn', () => {
+  it('keeps asymmetric color rows and depth-cut rays in one top-left convention', async () => {
+    const adapter = await navigator.gpu.requestAdapter();
+    if (adapter === null) return;
+    const device = await adapter.requestDevice();
+    const module = device.createShaderModule({ code: CLOUD_VIEW_FULLSCREEN_WGSL });
+    const pipeline = await device.createRenderPipelineAsync({
+      layout: 'auto',
+      vertex: { module, entryPoint: 'vs_main' },
+      fragment: {
+        module,
+        entryPoint: 'fs_main',
+        targets: [{ format: 'rgba8unorm' }],
+      },
+      primitive: { topology: 'triangle-list' },
+    });
+    const historyModule = device.createShaderModule({ code: CLOUD_HISTORY_FULLSCREEN_WGSL });
+    await device.createRenderPipelineAsync({
+      layout: 'auto',
+      vertex: { module: historyModule, entryPoint: 'vs_main' },
+      fragment: {
+        module: historyModule,
+        entryPoint: 'fs_main',
+        targets: [{ format: 'rgba16float' }, { format: 'rgba16float' }],
+      },
+      primitive: { topology: 'triangle-list' },
+    });
+    const noCloud = await render(device, pipeline, 1, 0);
+    expect(noCloud.rows).toEqual([20, 80, 140, 200]);
+    expect(noCloud.center).toBe(140);
+    const near = await render(device, pipeline, 0.1, 1);
+    const far = await render(device, pipeline, 1, 1);
+    expect(Math.abs(near.center - far.center)).toBeGreaterThan(2);
+    device.destroy();
+  });
+});