@forgeax/engine-render 0.1.32 → 0.1.34

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/bloom-admission.ts

@@ -0,0 +1,21 @@
+import type { BloomEnabled, Tonemap } from './components/camera';
+
+/**
+ * The one effective Standard Bloom admission used by graph, resource, and
+ * record owners. Authoring remains Camera-owned; this is only the derived
+ * zero/non-zero topology decision.
+ */
+export interface BloomAdmissionCamera {
+  readonly bloom: BloomEnabled;
+  readonly bloomIntensity: number;
+  readonly tonemap: Tonemap;
+}
+
+export function standardBloomAdmitted(camera: BloomAdmissionCamera | undefined): boolean {
+  return (
+    camera !== undefined &&
+    camera.bloom === 'on' &&
+    camera.bloomIntensity > 0 &&
+    camera.tonemap !== 'none'
+  );
+}

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();
+    }
+  });
+});