@forgeax/engine-render 0.1.31 → 0.1.33

package/src/__tests__/volumetric-fog-budget-recovery.integration.test.ts

@@ -1,10 +1,11 @@
 import { execFileSync } from 'node:child_process';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
-import { World } from '@forgeax/engine-ecs';
+import { Time, World } from '@forgeax/engine-ecs';
 import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
 import type {
   BindGroupLayoutDescriptor,
+  Buffer,
   RenderPipelineDescriptor,
   RhiAdapter,
   RhiDevice,
@@ -33,6 +34,7 @@ import {
   deriveVolumetricFogExtent,
   deriveVolumetricFogResolvedExtent,
   inspectVolumetricFogResources,
+  VOLUMETRIC_FOG_PARAMS_BYTES,
 } from '../volume/resources';
 import { resolveVolumeTemporalReset } from '../volume/temporal';
 
@@ -62,15 +64,12 @@ class RecoverableNullDevice extends RhiNullDevice {
   private readonly resolveLost: (info: LostInfo) => void;
   private readonly lostPromise: Promise<LostInfo>;
 
-  constructor() {
+  constructor(queue: RhiNullQueue = new RhiNullQueue()) {
     let resolveLost!: (info: LostInfo) => void;
     const lostPromise = new Promise<LostInfo>((resolve) => {
       resolveLost = resolve;
     });
-    super(
-      new RhiNullQueue(),
-      (bookkeeper, device) => new RhiNullCommandEncoder(bookkeeper, device),
-    );
+    super(queue, (bookkeeper, device) => new RhiNullCommandEncoder(bookkeeper, device));
     this.resolveLost = resolveLost;
     this.lostPromise = lostPromise;
   }
@@ -104,13 +103,44 @@ class RecoverableNullAdapter implements RhiAdapter {
   readonly limits: Readonly<Record<string, number>> = {};
   readonly devices: RecoverableNullDevice[] = [];
 
+  constructor(private readonly queueFactory: () => RhiNullQueue = () => new RhiNullQueue()) {}
+
   requestDevice(): Promise<Result<RhiDevice, RhiError>> {
-    const device = new RecoverableNullDevice();
+    const device = new RecoverableNullDevice(this.queueFactory());
     this.devices.push(device);
     return Promise.resolve(ok(device));
   }
 }
 
+interface CapturedQueueWrite {
+  readonly buffer: Buffer;
+  readonly offset: number;
+  readonly bytes: Uint8Array;
+}
+
+/** Captures the real record-stage volume parameter writes without adding a
+ * second render implementation. */
+class RecordingNullQueue extends RhiNullQueue {
+  readonly writes: CapturedQueueWrite[] = [];
+
+  override writeBuffer(
+    buffer: Buffer,
+    bufferOffset: number,
+    data: ArrayBufferView | ArrayBuffer,
+    dataOffset?: number,
+    size?: number,
+  ) {
+    const source =
+      data instanceof ArrayBuffer
+        ? new Uint8Array(data)
+        : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    const start = dataOffset ?? 0;
+    const end = size === undefined ? source.byteLength : start + size;
+    this.writes.push({ buffer, offset: bufferOffset, bytes: source.slice(start, end) });
+    return super.writeBuffer(buffer, bufferOffset, data, dataOffset, size);
+  }
+}
+
 function surfaceCanvas(width = 1920, height = 1080): HTMLCanvasElement {
   return { width, height, getContext: () => null } as unknown as HTMLCanvasElement;
 }
@@ -336,11 +366,11 @@ describe('volumetric fog budget and recovery contract', () => {
           label: 'volume-params',
           kind: 'buffer',
           origin: 'imported',
-          descriptor: { kind: 'buffer', size: 128 },
+          descriptor: { kind: 'buffer', size: VOLUMETRIC_FOG_PARAMS_BYTES },
           firstUse: 0,
           lastUse: 3,
           derivedUsage: 64,
-          byteSize: 128,
+          byteSize: VOLUMETRIC_FOG_PARAMS_BYTES,
         },
       ],
     } as const;
@@ -349,21 +379,25 @@ describe('volumetric fog budget and recovery contract', () => {
     expect(facts.sampleCount).toBe(960 * 540 * 64);
     expect(facts.resolvedPixelCount).toBe(960 * 540);
     expect(facts.currentBytes).toBe(960 * 540 * 8);
-    expect(facts.bufferBytes).toBe(128);
+    expect(facts.bufferBytes).toBe(VOLUMETRIC_FOG_PARAMS_BYTES);
     expect(facts.liveResourceCount).toBe(5);
     expect(facts.historyBytes).toBe(960 * 540 * 8 * 2);
     expect(facts.physicalResourceCount).toBe(5);
-    expect(facts.totalBytes).toBe(960 * 540 * 16 * 4 + 960 * 540 * 8 * 3 + 128);
+    expect(facts.totalBytes).toBe(
+      960 * 540 * 16 * 4 + 960 * 540 * 8 * 3 + VOLUMETRIC_FOG_PARAMS_BYTES,
+    );
     expect(facts.totalBytes).toBe(
       facts.currentBytes + facts.historyBytes + facts.scratchBytes + facts.bufferBytes,
     );
     expect(facts.totalBytes).toBeLessThanOrEqual(MAX_MEMORY_BYTES);
 
     const doubleBuffered = inspectVolumetricFogResources(graph, { parameterBufferCount: 2 });
-    expect(doubleBuffered.bufferBytes).toBe(256);
+    expect(doubleBuffered.bufferBytes).toBe(VOLUMETRIC_FOG_PARAMS_BYTES * 2);
     expect(doubleBuffered.liveResourceCount).toBe(6);
     expect(doubleBuffered.physicalResourceCount).toBe(6);
-    expect(doubleBuffered.totalBytes).toBe(960 * 540 * 16 * 4 + 960 * 540 * 8 * 3 + 256);
+    expect(doubleBuffered.totalBytes).toBe(
+      960 * 540 * 16 * 4 + 960 * 540 * 8 * 3 + VOLUMETRIC_FOG_PARAMS_BYTES * 2,
+    );
     expect(doubleBuffered.totalBytes).toBe(
       doubleBuffered.currentBytes +
         doubleBuffered.historyBytes +
@@ -372,6 +406,136 @@ describe('volumetric fog budget and recovery contract', () => {
     );
   });
 
+  it('uses the canonical World clock to bound real volume history reuse', async () => {
+    const queue = new RecordingNullQueue();
+    const adapter = new RecoverableNullAdapter(() => queue);
+    const backend = {
+      ...nullRhi,
+      requestAdapter: async () => ok(adapter),
+    };
+    const created = await constructRendererHost(
+      surfaceCanvas(640, 360),
+      { rhi: backend },
+      { shaderManifestUrl: VOLUME_MANIFEST },
+    );
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const { renderer } = created.value;
+    const world = new World();
+    const density = world.allocSharedRef('TextureAsset', densityAsset());
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 3] } },
+        {
+          component: Camera,
+          data: {
+            ...perspective({ fov: Math.PI / 4, aspect: 16 / 9 }),
+            tonemap: TONEMAP_ACES_FILMIC,
+          },
+        },
+      )
+      .unwrap();
+    const sun = world
+      .spawn({
+        component: DirectionalLight,
+        data: { direction: [-0.4, -0.8, -0.3], castShadow: true },
+      })
+      .unwrap();
+    world
+      .spawn({
+        component: VolumetricFog,
+        data: {
+          light: sun,
+          density,
+          boundsMin: [-1, -1, -1],
+          boundsMax: [1, 1, 1],
+          extinction: [0.2, 0.2, 0.2],
+          albedo: [0.8, 0.8, 0.8],
+          emission: [0, 0, 0],
+          anisotropy: 0,
+          maxDistance: 50,
+        },
+      })
+      .unwrap();
+
+    const lease = renderer.attach(world);
+    expect(lease.ok).toBe(true);
+    if (!lease.ok) return;
+    const request = {
+      leases: [lease.value],
+      camera: { lease: lease.value },
+      environment: { lease: lease.value },
+    } as const;
+    const drawAndRead = async (): Promise<{
+      readonly history: number;
+      readonly worldTime: number;
+      readonly delta: number;
+    }> => {
+      queue.writes.length = 0;
+      const frame = renderer.draw(request);
+      expect(frame.ok).toBe(true);
+      if (!frame.ok) return { history: -1, worldTime: -1, delta: -1 };
+      expect((await frame.value.completed).ok).toBe(true);
+      const paramsWrite = queue.writes
+        .filter((write) => write.offset === 0 && write.bytes.byteLength === 144)
+        .at(-1);
+      expect(paramsWrite).toBeDefined();
+      if (paramsWrite === undefined) return { history: -1, worldTime: -1, delta: -1 };
+      const historyWrite = queue.writes
+        .filter(
+          (write) =>
+            write.buffer === paramsWrite.buffer &&
+            write.offset === 31 * Float32Array.BYTES_PER_ELEMENT &&
+            write.bytes.byteLength === 3 * Float32Array.BYTES_PER_ELEMENT,
+        )
+        .at(-1);
+      expect(historyWrite).toBeDefined();
+      if (historyWrite === undefined) return { history: -1, worldTime: -1, delta: -1 };
+      return {
+        history: new Float32Array(
+          historyWrite.bytes.buffer,
+          historyWrite.bytes.byteOffset,
+          1,
+        )[0] as number,
+        worldTime: new Float32Array(
+          historyWrite.bytes.buffer,
+          historyWrite.bytes.byteOffset,
+          3,
+        )[1] as number,
+        delta: new Float32Array(
+          historyWrite.bytes.buffer,
+          historyWrite.bytes.byteOffset,
+          3,
+        )[2] as number,
+      };
+    };
+
+    world.update(1 / 60).unwrap();
+    const firstTime = world.getResource(Time).elapsed;
+    const first = await drawAndRead();
+    expect(first.worldTime).toBeCloseTo(firstTime, 5);
+    expect(first.history).toBe(0);
+
+    const stable = await drawAndRead();
+    expect(world.getResource(Time).elapsed).toBe(firstTime);
+    expect(stable.worldTime).toBeCloseTo(firstTime, 5);
+    expect(stable.history).toBe(1);
+
+    world.update(1 / 60).unwrap();
+    const movedTime = world.getResource(Time).elapsed;
+    const moved = await drawAndRead();
+    expect(moved.worldTime).toBeCloseTo(movedTime, 5);
+    expect(moved.worldTime).toBeGreaterThan(first.worldTime);
+    expect(moved.history).toBe(1);
+    expect(moved.delta).toBeCloseTo(1 / 60, 6);
+    expect(stable.delta).toBe(0);
+    for (let index = 0; index < 12; index += 1) world.update(1 / 60).unwrap();
+    const jumped = await drawAndRead();
+    expect(jumped.history).toBe(0);
+    expect(jumped.delta).toBeGreaterThan(0.1);
+    await renderer.dispose();
+  }, 30_000);
+
   it('derives a same-XY resolve descriptor when the packed raw extent is supplied alone', async () => {
     const adapter = await nullRhi.requestAdapter();
     expect(adapter.ok).toBe(true);