@forgeax/engine-render 0.1.33 → 0.1.34

package/src/temporal/gpu.ts

@@ -23,6 +23,13 @@ export const TEMPORAL_HISTORY_FORMATS = Object.freeze({
   stability: 'r8unorm',
 } as const);
 
+/** Cloud transport history shares the renderer temporal owner and ping-pong fence. */
+export const CLOUD_HISTORY_FORMATS = Object.freeze({
+  radiance: 'rgba16float',
+  transmittance: 'rgba16float',
+  depth: 'rgba16float',
+} as const);
+
 interface TemporalSurface {
   readonly texture: Texture;
   readonly view: TextureView;
@@ -40,6 +47,12 @@ export interface TemporalGpuState {
   readonly color: [TemporalSurface, TemporalSurface];
   readonly temporal: [TemporalSurface, TemporalSurface];
   readonly stability: [TemporalSurface, TemporalSurface];
+  /** Whether this candidate owns the optional cloud transport history MRT. */
+  readonly cloudHistoryEnabled: boolean;
+  /** Previous/current cloud radiance, transmittance and representative depth. */
+  readonly cloudRadiance: [TemporalSurface, TemporalSurface] | undefined;
+  readonly cloudTransmittance: [TemporalSurface, TemporalSurface] | undefined;
+  readonly cloudDepth: [TemporalSurface, TemporalSurface] | undefined;
   bindGroupLayout: BindGroupLayout | undefined;
   sampler: Sampler | undefined;
   temporalSampler: Sampler | undefined;
@@ -81,13 +94,22 @@ function createSurface(
   return { texture: texture.value, view: view.value };
 }
 
+function cloudHistoryExtent(width: number, height: number): { width: number; height: number } {
+  return {
+    width: Math.max(1, Math.ceil(width / 2)),
+    height: Math.max(1, Math.ceil(height / 2)),
+  };
+}
+
 function createState(
   device: RhiDevice,
   scope: DeviceScope,
   width: number,
   height: number,
+  cloudHistoryEnabled: boolean,
 ): TemporalGpuState {
   const childScope = scope.createChild(`${scope.owner}:temporal`);
+  const cloudExtent = cloudHistoryExtent(width, height);
   try {
     return {
       device,
@@ -138,6 +160,65 @@ function createState(
           TEMPORAL_HISTORY_FORMATS.stability,
         ),
       ],
+      cloudHistoryEnabled,
+      cloudRadiance: cloudHistoryEnabled
+        ? [
+            createSurface(
+              device,
+              childScope,
+              'cloud-history-radiance-a',
+              cloudExtent.width,
+              cloudExtent.height,
+            ),
+            createSurface(
+              device,
+              childScope,
+              'cloud-history-radiance-b',
+              cloudExtent.width,
+              cloudExtent.height,
+            ),
+          ]
+        : undefined,
+      cloudTransmittance: cloudHistoryEnabled
+        ? [
+            createSurface(
+              device,
+              childScope,
+              'cloud-history-transmittance-a',
+              cloudExtent.width,
+              cloudExtent.height,
+              CLOUD_HISTORY_FORMATS.transmittance,
+            ),
+            createSurface(
+              device,
+              childScope,
+              'cloud-history-transmittance-b',
+              cloudExtent.width,
+              cloudExtent.height,
+              CLOUD_HISTORY_FORMATS.transmittance,
+            ),
+          ]
+        : undefined,
+      cloudDepth: cloudHistoryEnabled
+        ? [
+            createSurface(
+              device,
+              childScope,
+              'cloud-history-depth-a',
+              cloudExtent.width,
+              cloudExtent.height,
+              CLOUD_HISTORY_FORMATS.depth,
+            ),
+            createSurface(
+              device,
+              childScope,
+              'cloud-history-depth-b',
+              cloudExtent.width,
+              cloudExtent.height,
+              CLOUD_HISTORY_FORMATS.depth,
+            ),
+          ]
+        : undefined,
       bindGroupLayout: undefined,
       sampler: undefined,
       temporalSampler: undefined,
@@ -180,26 +261,29 @@ export function getTemporalGpuState(
   scope: DeviceScope,
   width: number,
   height: number,
+  cloudHistoryRequested = false,
 ): TemporalGpuState {
+  // Graph preparation publishes this demand before any imported target is
+  // resolved. That makes the first TAA and cloud pass share one candidate,
+  // while a plain TAA frame allocates only its six TAA surfaces.
+  const wantsCloudHistory =
+    cloudHistoryRequested ||
+    frameState.pendingCloudHistoryActive === true ||
+    frameState.cloudHistoryActive === true;
+  const matches = (state: TemporalGpuState | undefined): state is TemporalGpuState =>
+    state !== undefined &&
+    state.scope === scope &&
+    state.width === width &&
+    state.height === height &&
+    // Cloud history is a demand-shaped part of the temporal allocation. Keep
+    // the two shapes distinct so turning CloudLayer off retires its six HDR
+    // surfaces instead of retaining them on an otherwise TAA-only frame.
+    state.cloudHistoryEnabled === wantsCloudHistory;
   const staged = frameState.temporalGpuState;
-  if (
-    staged !== undefined &&
-    staged.scope === scope &&
-    staged.width === width &&
-    staged.height === height
-  ) {
-    return staged;
-  }
+  if (matches(staged)) return staged;
   const existing = frameState.activeTemporalGpuState;
-  if (
-    existing !== undefined &&
-    existing.scope === scope &&
-    existing.width === width &&
-    existing.height === height
-  ) {
-    return existing;
-  }
-  const next = createState(device, scope, width, height);
+  if (matches(existing)) return existing;
+  const next = createState(device, scope, width, height, wantsCloudHistory);
   frameState.temporalGpuState = next;
   return next;
 }

package/src/temporal/inspection.ts

@@ -29,7 +29,13 @@ export interface TemporalInspection {
 }
 
 function gpuBytes(state: TemporalGpuState | undefined): number {
-  return state === undefined ? 0 : createTemporalCoverage(state.width, state.height).bytes;
+  if (state === undefined) return 0;
+  const taaBytes = createTemporalCoverage(state.width, state.height).bytes;
+  // The cloud owner adds six rgba16float surfaces (8 bytes per pixel) only
+  // when the candidate was admitted with cloud history demand. This is derived
+  // from the live state shape rather than reported as a fixed cloud estimate.
+  const cloudBytes = state.cloudHistoryEnabled ? state.width * state.height * 6 * 8 : 0;
+  return taaBytes + cloudBytes;
 }
 
 function gpuResources(state: TemporalGpuState | undefined): number {

package/src/temporal/standard-scene-data.ts

@@ -156,6 +156,11 @@ export function addStandardSceneDataPass(
     color: target,
     depth,
     selector: { LightMode: ['Deferred', 'Forward'] },
+    // The temporal producer runs before the Surface raw-depth/nearest-layer
+    // pair. Keep it on the ordinary opaque Standard lane rather than asking
+    // a medium material to assemble a bind group from resources that this
+    // pass cannot own yet.
+    recordMode: 'opaque',
     passKind: 'temporal',
     // The temporal producer re-rasterizes the current scene after the main
     // color pass has populated depth. Its output is a semantic motion target;

package/src/temporal/target-coverage-attachment.ts

@@ -64,6 +64,10 @@ export function addTargetCoveragePass(
     colorTargets: [target.coverage],
     depth: target.depth,
     selector: { LightMode: ['Deferred', 'Forward'] },
+    // Coverage is a generic Standard raster producer. Surface medium pixels
+    // are owned by the later paired nearest/color passes and have no raw-depth
+    // input at this point, so keep this attachment on the opaque lane.
+    recordMode: 'opaque',
     passKind: 'temporal',
     clearColor: [0, 0, 0, 0],
     depthLoadOp: 'clear',

package/src/transmission/__tests__/single-layer-medium.unit.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from 'vitest';
+import {
+  composeSingleLayerMediumColor,
+  integrateSingleLayerMedium,
+  isBelowSingleLayerMediumPlane,
+  resolveSingleLayerMediumBackground,
+} from '../single-layer-medium.js';
+
+const coefficients = {
+  absorption: [0.2, 0.4, 0.8] as const,
+  scattering: [0.1, 0.1, 0.1] as const,
+  ior: 1.333,
+  phaseG: 0.4,
+};
+
+describe('single-layer medium optics', () => {
+  it('uses Beer-Lambert transmission and the zero-extinction limit', () => {
+    const short = integrateSingleLayerMedium({ coefficients, distanceMeters: 1, cosTheta: 1 });
+    const long = integrateSingleLayerMedium({ coefficients, distanceMeters: 2, cosTheta: 1 });
+    expect(long.transmittance[0]).toBeLessThan(short.transmittance[0]);
+    expect(long.transmittance[1]).toBeLessThan(short.transmittance[1]);
+    expect(short.singleScatter[0]).toBeGreaterThan(0);
+    const empty = integrateSingleLayerMedium({
+      coefficients: { absorption: [0, 0, 0], scattering: [0, 0, 0], ior: 1.333 },
+      distanceMeters: 4,
+      cosTheta: 1,
+    });
+    expect(empty.transmittance).toEqual([1, 1, 1]);
+    expect(empty.singleScatter).toEqual([0, 0, 0]);
+    expect(empty.reflectance).toBeGreaterThan(0);
+    expect(empty.reflectance).toBeLessThan(1);
+    expect(
+      [...empty.transmittance, ...empty.singleScatter, empty.phase].every(Number.isFinite),
+    ).toBe(true);
+  });
+
+  it('keeps the zero-extinction limit and small-x RGB oracle continuous', () => {
+    const zeroExtinction = integrateSingleLayerMedium({
+      coefficients: {
+        absorption: [0, 0, 0],
+        scattering: [0, 0, 0],
+        ior: 1.333,
+      },
+      distanceMeters: 4,
+      cosTheta: 1,
+    });
+    expect(zeroExtinction.singleScatter).toEqual([0, 0, 0]);
+
+    const coefficients = {
+      absorption: [0, 0.000001, 0.25] as const,
+      scattering: [0.000001, 0.000001, 0.5] as const,
+      ior: 1.333,
+    };
+    const distanceMeters = 100000;
+    const optics = integrateSingleLayerMedium({
+      coefficients,
+      distanceMeters,
+      maxDistanceMeters: distanceMeters,
+      cosTheta: 1,
+    });
+    const sigmaT = [0.000001, 0.000002, 0.75];
+    const expected = sigmaT.map((extinction, index) => {
+      const x = extinction * distanceMeters;
+      const oneMinusExpNeg = x < 0.001 ? x * (1 - x / 2 + (x * x) / 6) : -Math.expm1(-x);
+      return ((coefficients.scattering[index] ?? 0) * oneMinusExpNeg) / extinction;
+    });
+    expect(optics.distanceMeters).toBe(distanceMeters);
+    expect(optics.singleScatter[0]).toBeCloseTo(expected[0] ?? 0, 12);
+    expect(optics.singleScatter[1]).toBeCloseTo(expected[1] ?? 0, 12);
+    expect(optics.singleScatter[2]).toBeCloseTo(expected[2] ?? 0, 12);
+    expect(optics.singleScatter.every(Number.isFinite)).toBe(true);
+  });
+
+  it('allocates Fresnel once and keeps coverage/foam as finite mixing weights', () => {
+    const optics = integrateSingleLayerMedium({ coefficients, distanceMeters: 1.5, cosTheta: 0.4 });
+    const color = composeSingleLayerMediumColor({
+      optics,
+      background: [0.2, 0.3, 0.4],
+      reflection: [1, 1, 1],
+      foamColor: [0.9, 0.9, 0.9],
+      coverage: 0.8,
+      foam: 0.25,
+    });
+    expect(color.every(Number.isFinite)).toBe(true);
+    expect(color.every((channel) => channel >= 0)).toBe(true);
+    expect(
+      composeSingleLayerMediumColor({
+        optics,
+        background: [0, 0, 0],
+        reflection: [0, 0, 0],
+        coverage: 0,
+      }),
+    ).toEqual([0, 0, 0]);
+  });
+
+  it('keeps endpoint admission on the undisturbed plane under a strongly tilted ripple', () => {
+    const surfacePosition = [0, 0, 0] as const;
+    const endpoint = [1, -0.1, 0] as const;
+    expect(
+      isBelowSingleLayerMediumPlane({
+        surfacePosition,
+        geometricNormal: [0, 1, 0],
+        endpoint,
+      }),
+    ).toBe(true);
+    // This shading normal would classify the same endpoint above water. It is
+    // deliberately excluded from the geometric-plane API and WGSL callsite.
+    expect(endpoint[0] * 0.995 + endpoint[1] * 0.1).toBeGreaterThan(0);
+  });
+
+  it('keeps refracted color and depth paired and reports conservative fallbacks', () => {
+    const base = {
+      original: { color: [0.1, 0.2, 0.3] as const, depthMeters: 8, uv: [0.5, 0.5] as const },
+      surfaceDepthMeters: 2,
+      maxDistanceMeters: 20,
+    };
+    expect(
+      resolveSingleLayerMediumBackground({
+        ...base,
+        refracted: { color: [0.4, 0.5, 0.6], depthMeters: 7, uv: [0.55, 0.5] },
+      }),
+    ).toMatchObject({ source: 'refracted', distanceMeters: 5 });
+    expect(
+      resolveSingleLayerMediumBackground({
+        ...base,
+        refracted: { color: [0.4, 0.5, 0.6], depthMeters: 1, uv: [0.55, 0.5] },
+      }),
+    ).toMatchObject({ source: 'unrefracted', reason: 'front', color: base.original.color });
+    expect(
+      resolveSingleLayerMediumBackground({
+        ...base,
+        refracted: { color: [0.4, 0.5, 0.6], depthMeters: 7, uv: [1.2, 0.5] },
+      }),
+    ).toMatchObject({ source: 'unrefracted', reason: 'edge' });
+    expect(
+      resolveSingleLayerMediumBackground({
+        ...base,
+        original: { color: [0, 0, 0], depthMeters: Number.NaN, uv: [0.5, 0.5] },
+        environment: [0.7, 0.8, 0.9],
+      }),
+    ).toMatchObject({ source: 'environment', reason: 'sky-miss' });
+    expect(
+      resolveSingleLayerMediumBackground({
+        ...base,
+        refracted: { color: [0.4, 0.5, 0.6], depthMeters: 7, uv: [-0.01, 0.5] },
+      }),
+    ).toMatchObject({ source: 'unrefracted', reason: 'edge', color: base.original.color });
+  });
+});

package/src/transmission/__tests__/standard-transmission.dawn.test.ts

@@ -8,7 +8,7 @@ import {
 } from '@forgeax/engine-rhi-webgpu';
 import { Transform } from '@forgeax/engine-scene';
 import type { TextureAsset } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
+import { afterAll, describe, expect, it } from 'vitest';
 import {
   Camera,
   DirectionalLight,
@@ -32,17 +32,18 @@ const GPU_MAP_MODE_READ = 0x0001;
 const TEST_REACTIVE = 0;
 const LIGHTWEIGHT_DAWN = process.env.FORGEAX_DAWN_LIGHTWEIGHT === '1';
 const ROSTER_SMOKE = process.env.FORGEAX_DAWN_ROSTER_SMOKE === '1';
-const requestedSmokeFrames = Number.parseInt(process.env.SMOKE_MIN_FRAMES ?? '300', 10);
+const requestedSmokeFrames = Number.parseInt(process.env.SMOKE_MIN_FRAMES ?? '60', 10);
 const ROSTER_SMOKE_FRAMES =
-  Number.isInteger(requestedSmokeFrames) && requestedSmokeFrames > 0 ? requestedSmokeFrames : 300;
+  Number.isInteger(requestedSmokeFrames) && requestedSmokeFrames > 0 ? requestedSmokeFrames : 60;
 
 const ENGINE_MANIFEST = await (async () => {
   const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
   return buildEngineShaderManifest();
 })();
-const ENGINE_MANIFEST_URL = `data:application/json,${encodeURIComponent(
-  JSON.stringify(ENGINE_MANIFEST),
-)}`;
+const ENGINE_MANIFEST_URL = URL.createObjectURL(
+  new Blob([JSON.stringify(ENGINE_MANIFEST)], { type: 'application/json' }),
+);
+afterAll(() => URL.revokeObjectURL(ENGINE_MANIFEST_URL));
 const DAWN_BACKEND: RhiBackendPack = {
   rhi,
   createShaderModule,
@@ -360,7 +361,7 @@ function luma(pixel: readonly [number, number, number, number]): number {
 }
 
 describe('Standard transmission Dawn ROI', () => {
-  it('completes a 300-frame transmission stream without renderer errors', async () => {
+  it('completes a 60-frame transmission stream without renderer errors', async () => {
     const result = await renderCase(
       {
         name: 'sustained-transmission',
@@ -372,9 +373,9 @@ describe('Standard transmission Dawn ROI', () => {
         attenuationDistance: 2,
         renderPath: 'forward',
       },
-      300,
+      60,
     );
-    expect(result.framesObserved).toBe(300);
+    expect(result.framesObserved).toBe(60);
     expect(result.errors).toEqual([]);
     expect(result.observation).toBe(true);
     expect(result.passNames).toContain('transmission-forward');
@@ -537,7 +538,7 @@ describe('Standard transmission Dawn ROI', () => {
   }, 120_000);
 
   if (ROSTER_SMOKE) {
-    it('emits the canonical 300-frame Dawn roster receipt', async () => {
+    it('emits the canonical 60-frame Dawn roster receipt', async () => {
       const result = await renderCase(
         {
           name: 'roster-stability',
@@ -551,7 +552,7 @@ describe('Standard transmission Dawn ROI', () => {
         },
         ROSTER_SMOKE_FRAMES,
       );
-      expect(result.framesObserved).toBeGreaterThanOrEqual(300);
+      expect(result.framesObserved).toBeGreaterThanOrEqual(60);
       expect(result.observation).toBe(true);
       expect(result.errors).toEqual([]);
       process.stdout.write(`[smoke] frames observed=${result.framesObserved}\n`);