@forgeax/engine-render 0.1.36 → 0.1.37

package/src/__tests__/ibl/precompute-submission.unit.test.ts

@@ -0,0 +1,123 @@
+import type { Result } from '@forgeax/engine-rhi';
+import { createShaderModule, RhiNullAdapter, RhiNullDevice } from '@forgeax/engine-rhi-null';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { DeviceScope } from '../../device/device-scope';
+import {
+  createFaceUniformsBuffer,
+  createPrefilterUniformsBuffer,
+} from '../../device/gpu-residency';
+import {
+  createIblPipelines,
+  getOrCreateIblCache,
+  type RunIblPrecomputeOptions,
+  runIblPrecompute,
+} from '../../ibl/IblPipelineCache';
+
+function unwrap<T, E>(result: Result<T, E>): T {
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+async function fixture() {
+  const device = unwrap(await new RhiNullAdapter().requestDevice());
+  if (!(device instanceof RhiNullDevice)) throw new Error('Expected null backend');
+  const scope = DeviceScope.create(1, 'ibl-submission-test');
+  unwrap(await createIblPipelines(scope, device, createShaderModule));
+  const texture = unwrap(
+    device.createTexture({
+      size: { width: 4, height: 4, depthOrArrayLayers: 6 },
+      format: 'rgba16float',
+      usage: 20,
+      mipLevelCount: 1,
+      sampleCount: 1,
+      dimension: '2d',
+    }),
+  );
+  const view = unwrap(device.createTextureView(texture, { dimension: 'cube' }));
+  const options: RunIblPrecomputeOptions = {
+    scope,
+    device,
+    equirectGpuTex: texture,
+    equirectView: view,
+    cubeGpuTex: texture,
+    cubeView: view,
+    cubeFaceViews: Array.from({ length: 6 }, (_, face) =>
+      unwrap(
+        device.createTextureView(texture, {
+          dimension: '2d',
+          baseArrayLayer: face,
+          arrayLayerCount: 1,
+        }),
+      ),
+    ),
+    faceUniformsBuffer: unwrap(createFaceUniformsBuffer(device)),
+    prefilterUniformsBuffer: unwrap(createPrefilterUniformsBuffer(device)),
+    cubeVertexBuffer: unwrap(
+      device.createBuffer({ size: 432, usage: 32, mappedAtCreation: false }),
+    ),
+  };
+  return { ...options, cache: getOrCreateIblCache(scope), options };
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('IBL precompute completion boundaries', () => {
+  it('fences each prefilter face and publishes only after the final completion', async () => {
+    const { device, scope, cache, options } = await fixture();
+    const passes: string[][] = [];
+    let offset = 0;
+    const submit = device.queue.submit.bind(device.queue);
+    vi.spyOn(device.queue, 'submit').mockImplementation((buffers) => {
+      passes.push(device.framePassNames.slice(offset));
+      offset = device.framePassNames.length;
+      return submit(buffers);
+    });
+    let release!: () => void;
+    const lastFence = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    vi.spyOn(device.queue, 'onSubmittedWorkDone').mockImplementation(async () => {
+      expect(cache.prefilterTexture).toBeUndefined();
+      expect(cache.prefilterBakeCount).toBe(0);
+      if (passes.at(-1)?.includes('ibl-brdf-lut')) await lastFence;
+    });
+    const result = runIblPrecompute(options);
+    try {
+      await vi.waitFor(() => expect(passes.at(-1)).toEqual(['ibl-brdf-lut']));
+      expect(passes.filter((batch) => batch.includes('ibl-prefilter'))).toEqual(
+        Array.from({ length: 30 }, () => ['ibl-prefilter']),
+      );
+      expect(cache.prefilterTexture).toBeUndefined();
+      expect(device.totalDrawCount).toBe(43);
+    } finally {
+      release();
+    }
+    expect(await result).toEqual({ ok: true, value: { submitted: true } });
+    expect(cache.prefilterTexture).toBeDefined();
+    expect([cache.irradianceBakeCount, cache.prefilterBakeCount, cache.brdfLutBakeCount]).toEqual([
+      1, 1, 1,
+    ]);
+    scope.dispose();
+  });
+
+  it.each([
+    'fence failure',
+    'scope retirement',
+  ])('stops before the next prefilter face after %s', async (failure) => {
+    const { device, scope, cache, options } = await fixture();
+    vi.spyOn(device.queue, 'onSubmittedWorkDone').mockImplementation(async () => {
+      if (!device.framePassNames.includes('ibl-prefilter')) return;
+      if (failure === 'fence failure') throw new Error('device lost');
+      scope.abandon();
+    });
+    const result = await runIblPrecompute(options);
+    expect(result).toMatchObject({ ok: false, error: { code: 'ibl-precompute-not-dispatched' } });
+    expect(device.framePassNames.filter((name) => name === 'ibl-prefilter')).toHaveLength(1);
+    expect(device.framePassNames).not.toContain('ibl-brdf-lut');
+    expect(cache.prefilterTexture).toBeUndefined();
+    expect([cache.irradianceBakeCount, cache.prefilterBakeCount, cache.brdfLutBakeCount]).toEqual([
+      0, 0, 0,
+    ]);
+    scope.dispose();
+  });
+});

package/src/__tests__/ibl-residency-publication.unit.test.ts

@@ -67,22 +67,6 @@ describe('IBL residency publication', () => {
     expect(candidateWrites).toBeLessThan(fence);
   });
 
-  it('fences each IBL stage before recording the next stage', () => {
-    const runStart = iblSource.indexOf('export async function runIblPrecompute(');
-    const stages = ['equirect-to-cube', 'prefilter', 'brdf-lut'];
-    let previous = runStart;
-    for (const stage of stages) {
-      const marker = iblSource.indexOf(`await submitStage('${stage}'`, previous);
-      expect(marker).toBeGreaterThan(previous);
-      previous = marker;
-    }
-    expect(iblSource.match(/await submitStage\('/g)).toHaveLength(stages.length);
-    expect(iblSource).toContain('await device.queue.onSubmittedWorkDone()');
-    expect(
-      iblSource.indexOf('cache.irradianceTexture = promoted.irradianceTexture'),
-    ).toBeGreaterThan(previous);
-  });
-
   it('does not promote or increment counters after a failed stage', () => {
     const runStart = iblSource.indexOf('export async function runIblPrecompute(');
     const promotion = iblSource.indexOf(

package/src/assembly/host-contract.ts

@@ -14,7 +14,7 @@ import type { ObservationUnavailableError, RenderError } from '../errors/render'
 import type { RenderFeature, RenderFeatureDiagnostics } from '../features/types';
 import type { GpuDrivenProductionInspection, LodOcclusionInspection } from '../inspection-types';
 import type { MeshMaterialBindingObservation } from '../mesh-material-bindings';
-import type { PublishedRenderFrameInput } from '../publication/contract';
+import type { PublishedRenderFrameInput, RenderPublicationIdentity } from '../publication/contract';
 import type { FrameObservation, FrameObservationOptions } from '../record/frame';
 import type { CurrentGraphTarget, GraphTargetCaptureRequest } from '../record/frame-snapshot';
 import type {
@@ -110,7 +110,7 @@ export interface RendererHostImplementation {
   destroyRenderTarget(target: RenderTarget): RenderResult<void, RenderError>;
   setProfile(profile: RenderProfile): RenderResult<void, RenderError>;
   /** Detached world bounds for one record in the last extracted World; undefined if unavailable. */
-  bounds(world: World, entity: number): RenderSceneBounds | undefined;
+  bounds(world: World | RenderPublicationIdentity, entity: number): RenderSceneBounds | undefined;
   inspect(): RenderInspection;
   /**
    * Internal bounded inspection for high-cardinality producers. The public

package/src/gpu-driven/production-raster.ts

@@ -1405,7 +1405,7 @@ interface GpuDrivenResidencyValidationCache extends GpuDrivenResidencyValidation
 
 interface GpuDrivenCpuValidationTelemetryCache {
   readonly cacheKey: string;
-  readonly validated: readonly { readonly source: RenderableSnapshot }[];
+  readonly validatedSources: readonly RenderableSnapshot[];
   readonly gpuOwnedDrawKeys: ReadonlySet<string>;
   readonly worldKeys: readonly number[] | undefined;
   readonly gpuOwnedDrawCount: number;
@@ -1421,6 +1421,17 @@ interface GpuDrivenCpuValidationTelemetryCache {
   readonly blockedDrawItems: number;
 }
 
+function sameValidatedSourceSequence(
+  expected: readonly RenderableSnapshot[],
+  actual: readonly { readonly source: RenderableSnapshot }[],
+): boolean {
+  if (expected.length !== actual.length) return false;
+  for (let index = 0; index < expected.length; index += 1) {
+    if (expected[index] !== actual[index]?.source) return false;
+  }
+  return true;
+}
+
 function sameIdentitySequence<T extends object>(
   expected: readonly T[],
   actual: readonly T[],
@@ -3834,7 +3845,7 @@ export class GpuDrivenProduction {
       cacheKey !== undefined &&
       cached !== undefined &&
       cached.cacheKey === cacheKey &&
-      cached.validated === validated &&
+      sameValidatedSourceSequence(cached.validatedSources, validated) &&
       cached.gpuOwnedDrawKeys === gpuOwnedDrawKeys &&
       cached.worldKeys === worldKeys
     ) {
@@ -3920,7 +3931,7 @@ export class GpuDrivenProduction {
     if (cacheKey !== undefined) {
       this.cpuValidationTelemetryCache = {
         cacheKey,
-        validated,
+        validatedSources: validated.map((row) => row.source),
         gpuOwnedDrawKeys,
         worldKeys,
         gpuOwnedDrawCount: this.gpuOwnedDrawItems,

package/src/ibl/IblPipelineCache.ts

@@ -1031,12 +1031,13 @@ export async function runIblPrecompute(
       pass.setVertexBuffer(0, opts.cubeVertexBuffer);
       pass.draw(6, 1, face * 6, 0);
       pass.end();
+
+      // Bound software-GPU work just as for irradiance; preserve every sample.
+      const faceStage = await submitStage(`prefilter-mip-${mip}-face-${face}`, true);
+      if (!faceStage.ok) return err(faceStage.error);
     }
   }
 
-  const prefilterStage = await submitStage('prefilter', true);
-  if (!prefilterStage.ok) return err(prefilterStage.error);
-
   // (d) brdf-lut: fullscreen triangle.
   {
     const pass: RhiRenderPassEncoder = encoder.beginRenderPass({

package/src/publication/__tests__/publication.integration.test.ts

@@ -71,6 +71,20 @@ function fixture() {
 }
 
 describe('native render publication', () => {
+  it('queries detached bounds by publication identity and rejects another epoch', () => {
+    const f = fixture();
+    const identity = { source: 'publication-test', epoch: 1 };
+    expect(f.scene.bounds(identity, f.first)).toBeUndefined();
+    f.publish();
+    const bounds = f.scene.bounds(identity, f.first);
+    expect(bounds).toBeDefined();
+    expect(f.scene.bounds({ ...identity, epoch: 2 }, f.first)).toBeUndefined();
+    expect(f.scene.bounds({ source: 'other', epoch: 1 }, f.first)).toBeUndefined();
+    if (bounds !== undefined) (bounds.min as number[])[0] = -999;
+    expect(f.scene.bounds(identity, f.first)?.min[0]).not.toBe(-999);
+    f.publisher.dispose();
+  });
+
   it('publishes a numeric baseline, observes no static delta and retains the same CPU slots', () => {
     const f = fixture();
     const initial = f.publish();

package/src/render-contract.ts

@@ -478,8 +478,8 @@ export interface Renderer {
   destroyRenderTarget(target: RenderTarget): RenderResult<void, RenderError>;
   setProfile(profile: RenderProfile): RenderResult<void, RenderError>;
   state(): RendererState;
-  /** Detached world bounds for one record in the last extracted World; undefined if unavailable. */
-  bounds(world: World, entity: number): RenderSceneBounds | undefined;
+  /** Detached bounds from an extracted World or the bound publication source; undefined if unavailable. */
+  bounds(world: World | RenderPublicationIdentity, entity: number): RenderSceneBounds | undefined;
   inspect(): RenderInspection;
   observe(
     receipt: FrameReceipt,

package/src/render-system.ts

@@ -1,6 +1,6 @@
 import { projectCaptureScene } from './capture/scene-projection';
 import { renderMaterialContext } from './extract/material-context';
-import { RenderPublicationError } from './publication/contract';
+import { RenderPublicationError, type RenderPublicationIdentity } from './publication/contract';
 import { preparePublicationGeometry } from './publication/prepare-geometry';
 import type { PreparedRenderPublication } from './publication/receiver';
 import { type RenderResourceScope, renderTime } from './publication/resource-scope';
@@ -357,7 +357,7 @@ export interface RecoveryProductionEvidence {
  * whose shader identity is `forgeax::default-standard-pbr`).
  */
 export interface RenderSystem {
-  bounds(world: World, entity: number): RenderSceneBounds | undefined;
+  bounds(world: World | RenderPublicationIdentity, entity: number): RenderSceneBounds | undefined;
   /** Publish one renderer-owned read-only Surface dynamic page for the next frame. */
   setSurfaceDynamicInput(frame: SurfaceDynamicInputFrame | undefined): void;
   /** Complete explicit SSR capability preparation before drawing a device generation. */

package/src/scene/render-scene.ts

@@ -29,6 +29,7 @@ import type { InstanceProjectionStore } from '../instances';
 import { fingerprintNumericArray, InstanceBoundsCache } from '../instances-derived-bounds';
 import type { PointsLinesInspection } from '../points-lines/inspection';
 import type { PointsLinesRetainedSnapshot } from '../points-lines/snapshot';
+import type { RenderPublicationIdentity } from '../publication/contract';
 import type { PreparedRenderPublication } from '../publication/receiver';
 import type { RenderResourceScope } from '../publication/resource-scope';
 import { worldEntityKey } from '../record/frame-snapshot';
@@ -2568,9 +2569,10 @@ export class PersistentRenderScene {
   }
 
   /** Read existing culling bounds; never expose cached mutable arrays. */
-  bounds(world: World, entity: number): RenderSceneBounds | undefined {
+  bounds(world: World | RenderPublicationIdentity, entity: number): RenderSceneBounds | undefined {
     const entry = this.composition;
-    const worldId = entry?.worlds.indexOf(world) ?? -1;
+    const identity = 'source' in world ? `${world.source}:${world.epoch}` : world.identity;
+    const worldId = entry?.worlds.findIndex((source) => source.identity === identity) ?? -1;
     if (entry === undefined || worldId < 0) return undefined;
     const slot = entry.projection.slot(worldId, entity);
     if (slot === undefined) return undefined;