@forgeax/engine-render 0.1.21 → 0.1.24

package/src/record/__tests__/recovery-pipeline.unit.test.ts

@@ -0,0 +1,124 @@
+import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+import { describe, expect, it } from 'vitest';
+import { makeZeroCameraFallbackSnapshot, type ValidatedRenderable } from '../frame-snapshot';
+import {
+  createRecoveryColdWorkGuard,
+  prepareRecoveryPipelineReadiness,
+} from '../recovery-pipeline';
+import type { PipelineState, RenderSystemInternals } from '../render-context';
+
+function probeRenderable(probe: boolean): ValidatedRenderable {
+  const material = {
+    baseColor: [1, 1, 1],
+    metallic: 0,
+    roughness: 1,
+    materialShaderId: 'forgeax::default-standard-pbr',
+  } as never;
+  return {
+    source: {
+      material,
+      materials: [material],
+      ...(probe ? { probeBlendRecord: {} } : {}),
+    },
+    mesh: {
+      layoutProjection: deriveVertexLayoutProjection({
+        position: new Float32Array(0),
+        normal: new Float32Array(0),
+        uv: new Float32Array(0),
+        tangent: new Float32Array(0),
+      }),
+      indexFormat: 'uint32',
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 3,
+          vertexCount: 3,
+          topology: 'triangle-list',
+          materialSlot: 0,
+        },
+      ],
+    },
+  } as never;
+}
+
+function recoveryReadinessFor(
+  renderable: ValidatedRenderable,
+  reflectionFallbackAvailable = false,
+) {
+  const pipeline = {} as never;
+  const internals = {
+    device: { caps: { backendKind: 'webgpu', storageBuffer: true } },
+    getMaterialShaderPipelineEntry: (..._args: unknown[]) => ({
+      pipeline,
+      group2Contract: 'cluster' as const,
+    }),
+  } as unknown as RenderSystemInternals;
+  const pipelineState = {
+    colorAttachmentFormat: 'bgra8unorm',
+  } as unknown as PipelineState;
+  return prepareRecoveryPipelineReadiness({
+    internals,
+    pipelineState,
+    camera: makeZeroCameraFallbackSnapshot(),
+    standardLighting: { kind: 'no-local-lights' } as never,
+    validated: [renderable],
+    dispatch: [],
+    shadowCastersActive: false,
+    splitLdrSprite: false,
+    reflectionFallbackAvailable,
+  });
+}
+
+describe('recovery first-frame cold-work guard', () => {
+  it('prepares the probe-enabled Standard PBR variant used by the live record path', () => {
+    const readiness = recoveryReadinessFor(probeRenderable(true));
+    const standardPbr = readiness.pipelineSpecs.find(
+      (spec) => spec.shader.id === 'forgeax::default-standard-pbr',
+    );
+
+    expect(standardPbr?.shader.variantSet).toContain('PROBE_BLEND_AVAILABLE=true');
+  });
+
+  it('does not add the probe ABI to a Standard PBR renderable without a record', () => {
+    const readiness = recoveryReadinessFor(probeRenderable(false));
+    const standardPbr = readiness.pipelineSpecs.find(
+      (spec) => spec.shader.id === 'forgeax::default-standard-pbr',
+    );
+
+    expect(standardPbr?.shader.variantSet).not.toContain('PROBE_BLEND_AVAILABLE=true');
+  });
+
+  it('prepares the Standard PBR reflection fallback MRT variant', () => {
+    const readiness = recoveryReadinessFor(probeRenderable(false), true);
+    const standardPbr = readiness.pipelineSpecs.find(
+      (spec) => spec.shader.id === 'forgeax::default-standard-pbr',
+    );
+
+    expect(standardPbr?.shader.variantSet).toContain('REFLECTION_FALLBACK_AVAILABLE=true');
+    expect(standardPbr?.attachments.colorFormats).toEqual(['rgba16float', 'rgba16float']);
+  });
+
+  it('accepts a prepared candidate with no first-frame cold work', () => {
+    const guard = createRecoveryColdWorkGuard();
+
+    guard.arm();
+    expect(() => guard.finish()).not.toThrow();
+    expect(() => guard.finish()).not.toThrow();
+  });
+
+  it.each([
+    [
+      'pipeline',
+      (guard: ReturnType<typeof createRecoveryColdWorkGuard>) => guard.notePipelineColdWork(),
+    ],
+    [
+      'upload',
+      (guard: ReturnType<typeof createRecoveryColdWorkGuard>) => guard.noteUploadColdWork(),
+    ],
+  ] as const)('hard-fails a first-frame %s miss before submission', (_kind, note) => {
+    const guard = createRecoveryColdWorkGuard();
+
+    guard.arm();
+    expect(() => note(guard)).toThrow(/recovery first frame performed cold/);
+  });
+});

package/src/record/__tests__/sprite-material-abi.unit.test.ts

@@ -1,10 +1,27 @@
 import type { Buffer, Sampler, TextureView } from '@forgeax/engine-rhi';
 import { describe, expect, it } from 'vitest';
 import { assembleMaterialWithSkylightEntries } from '../../ibl/skylight-bind-group';
+import { defaultViewForUserRegionField } from '../main-pass-material';
 import { buildSpritePassBaseMaterialEntries } from '../main-pass-sprite-draws';
 import type { PipelineState } from '../render-context';
 
 describe('sprite Standard material ABI', () => {
+  it('uses the dedicated neutral anisotropy fallback instead of white', () => {
+    const white = {} as TextureView;
+    const anisotropy = {} as TextureView;
+    const pipelineState = {
+      defaultWhiteTextureView: white,
+      defaultAnisotropyTextureView: anisotropy,
+      defaultNormalTextureView: {} as TextureView,
+      fallbackTextureView: {} as TextureView,
+    } as PipelineState;
+
+    expect(defaultViewForUserRegionField('anisotropyTexture', pipelineState)).toBe(anisotropy);
+    expect(defaultViewForUserRegionField('baseColorTexture', pipelineState)).toBe(
+      pipelineState.fallbackTextureView,
+    );
+  });
+
   it('covers transmission and thickness before IBL injection', () => {
     const sampler = {} as Sampler;
     const white = {} as TextureView;
@@ -21,14 +38,12 @@ describe('sprite Standard material ABI', () => {
     const entries = buildSpritePassBaseMaterialEntries(pipelineState, spriteTexture);
 
     expect(entries.map((entry) => entry.binding)).toEqual([
-      0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16,
+      0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
     ]);
     expect(entries[13]).toMatchObject({ binding: 13, resource: { kind: 'sampler' } });
     expect(entries[14]).toMatchObject({ binding: 14, resource: { kind: 'textureView' } });
-    expect(entries[15]).toMatchObject({ binding: 15, resource: { kind: 'sampler' } });
-    expect(entries[16]).toMatchObject({ binding: 16, resource: { kind: 'textureView' } });
     expect(entries[2]?.resource).toMatchObject({ kind: 'textureView', value: spriteTexture });
-    expect(entries).toHaveLength(17);
+    expect(entries).toHaveLength(15);
 
     const merged = assembleMaterialWithSkylightEntries(entries, {
       irradianceView: {} as TextureView,
@@ -39,19 +54,19 @@ describe('sprite Standard material ABI', () => {
       brdfLutSampler: sampler,
       intensityBuffer: {} as Buffer,
     });
-    expect(merged[17]).toMatchObject({
-      binding: 17,
+    expect(merged[15]).toMatchObject({
+      binding: 15,
       resource: { kind: 'textureView' },
     });
-    expect(merged[24]).toMatchObject({
-      binding: 24,
+    expect(merged[22]).toMatchObject({
+      binding: 22,
       resource: { kind: 'sampler', value: sampler },
     });
-    expect(merged[25]).toMatchObject({
-      binding: 25,
+    expect(merged[23]).toMatchObject({
+      binding: 23,
       resource: { kind: 'textureView' },
     });
-    expect(merged).toHaveLength(26);
+    expect(merged).toHaveLength(24);
 
     const backdrop = {} as TextureView;
     const active = assembleMaterialWithSkylightEntries(
@@ -67,8 +82,8 @@ describe('sprite Standard material ABI', () => {
       },
       { sampler, backdropView: backdrop },
     );
-    expect(active[25]).toMatchObject({
-      binding: 25,
+    expect(active[23]).toMatchObject({
+      binding: 23,
       resource: { kind: 'textureView', value: backdrop },
     });
   });

package/src/record/__tests__/standard-pbr-ubo-layout.unit.test.ts

@@ -14,7 +14,7 @@ describe('Standard PBR UBO layout', () => {
       derived.coordinateRecords.map((record) => [record.parameter, record.offset]),
     );
 
-    expect(derived.totalBytes).toBe(384);
+    expect(derived.totalBytes).toBe(736);
     expect(numeric.get('normalScale')).toBe(92);
     expect(numeric.get('transmission')).toBe(96);
     expect(numeric.get('ior')).toBe(100);
@@ -26,6 +26,26 @@ describe('Standard PBR UBO layout', () => {
     expect(coordinates.get('thicknessTexture')).toBe(352);
   });
 
+  it('reserves the physical-layer tail required by the clearcoat shader ABI', () => {
+    const material = {
+      baseColor: vec3.create(0.7, 0.7, 0.7),
+      metallic: 0,
+      roughness: 0.4,
+      materialShaderId: 'forgeax::default-standard-pbr',
+      materialParamSchema: DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+      paramSnapshot: {
+        clearcoat: 0.8,
+        clearcoatRoughness: 0.2,
+        clearcoatNormalScale: 0.75,
+      },
+    } satisfies MaterialSnapshot;
+    const payload = buildPbrMaterialUboPayload(material);
+    const f32 = new Float32Array(payload.buffer);
+
+    expect(payload.byteLength).toBe(736);
+    expect(f32.slice(108, 111)).toEqual(new Float32Array([0.8, 0.2, 0.75]));
+  });
+
   it('writes transmission scalars and defaults at the reflected offsets', () => {
     const material = {
       baseColor: vec3.create(0.7, 0.7, 0.7),
@@ -33,6 +53,7 @@ describe('Standard PBR UBO layout', () => {
       roughness: 0.4,
       normalScale: 0.25,
       materialShaderId: 'forgeax::default-standard-pbr',
+      materialParamSchema: DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
       paramSnapshot: {
         transmission: 0.75,
         ior: 1.6,
@@ -48,7 +69,7 @@ describe('Standard PBR UBO layout', () => {
     );
   });
 
-  it('uses all eight identity coordinate records in the no-snapshot fallback', () => {
+  it('uses all seven user-region identity coordinate records in the no-snapshot fallback', () => {
     const material = {
       baseColor: vec3.create(0.7, 0.7, 0.7),
       metallic: 0,
@@ -60,8 +81,30 @@ describe('Standard PBR UBO layout', () => {
     applyMaterialTextureUvScales(payload, material, new World());
 
     const f32 = new Float32Array(payload.buffer);
-    expect(f32.slice(32, 96)).toEqual(
-      new Float32Array(Array(8).fill([0, 0, 1, 1, 0, 0, 1, 1]).flat()),
+    expect(f32.slice(32, 88)).toEqual(
+      new Float32Array(Array(7).fill([0, 0, 1, 1, 0, 0, 1, 1]).flat()),
     );
   });
+
+  it('keeps the physical tail intact when standard coordinates are projected', () => {
+    const material = {
+      baseColor: vec3.create(0.7, 0.7, 0.7),
+      metallic: 0,
+      roughness: 0.4,
+      materialShaderId: 'forgeax::default-standard-pbr',
+      materialParamSchema: DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+      paramSnapshot: {
+        clearcoat: 1,
+        clearcoatRoughness: 0.18,
+        clearcoatNormalScale: 0.75,
+      },
+    } satisfies MaterialSnapshot;
+    const payload = buildPbrMaterialUboPayload(material);
+
+    applyMaterialTextureUvScales(payload, material, new World());
+
+    const f32 = new Float32Array(payload.buffer);
+    expect(f32.slice(108, 111)).toEqual(new Float32Array([1, 0.18, 0.75]));
+    expect(f32.slice(32, 40)).toEqual(new Float32Array([0, 0, 1, 1, 0, 0, 1, 1]));
+  });
 });

package/src/record/__tests__/temporal-payload.unit.test.ts

@@ -2,7 +2,7 @@ import { vec3 } from '@forgeax/engine-math';
 import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
 import { describe, expect, it } from 'vitest';
 import type { CameraSnapshot } from '../../render-contract';
-import type { RenderableSnapshot, SpotLightSnapshot } from '../../render-system-extract';
+import type { RenderableSnapshot } from '../../render-system-extract';
 import type { TemporalView } from '../../temporal/temporal-view';
 import type { ValidatedRenderable } from '../frame-snapshot';
 import { uploadMeshSsboBatch } from '../mesh-ssbo';
@@ -98,27 +98,8 @@ function temporalView(): TemporalView {
 }
 
 describe('temporal GPU payloads', () => {
-  it('publishes a projector-only SpotLight matrix into the explicit lane-0 contract', () => {
+  it('keeps the zero-directional fallback direction finite and unscaled', () => {
     const { queue, uploads } = recordingQueue();
-    const projectorMatrix = translatedMatrix(9);
-    const projector: SpotLightSnapshot = {
-      kind: 'spot',
-      entity: 4,
-      position: vec3.create(0, 2, 0),
-      direction: vec3.create(0, -1, 0),
-      color: vec3.create(1, 1, 1),
-      intensity: 1,
-      invRangeSquared: 0.04,
-      cosInner: 0.95,
-      cosOuter: 0.8,
-      castShadow: false,
-      lightViewProj: projectorMatrix,
-      mapSize: 512,
-      nearPlane: 0.1,
-      farPlane: 25,
-      shadowAtlasTile: -1,
-      projectorAsset: { kind: 'texture' } as never,
-    };
     writeViewUbo(
       queue,
       {} as Buffer,
@@ -126,17 +107,37 @@ describe('temporal GPU payloads', () => {
       {
         kind: 'directional',
         direction: vec3.create(0, -1, 0),
+        color: vec3.create(0, 0, 0),
+        intensity: 0,
+      },
+      { point: [], spot: [] } as never,
+      [],
+    );
+
+    const payload = new Float32Array(uploads[0]?.buffer ?? new ArrayBuffer(0));
+    expect(Array.from(payload.slice(16, 19))).toEqual([0, -1, 0]);
+    expect(Array.from(payload.slice(20, 23))).toEqual([0, 0, 0]);
+    expect(Array.from(payload.slice(16, 23)).every(Number.isFinite)).toBe(true);
+  });
+
+  it('keeps directional orientation independent from light intensity', () => {
+    const { queue, uploads } = recordingQueue();
+    writeViewUbo(
+      queue,
+      {} as Buffer,
+      camera(),
+      {
+        kind: 'directional',
+        direction: vec3.create(0.25, -0.5, 0.75),
         color: vec3.create(1, 1, 1),
-        intensity: 1,
+        intensity: 4,
       },
-      { point: [], spot: [projector] } as never,
-      [projector],
-      undefined,
-      undefined,
-      0,
+      { point: [], spot: [] } as never,
+      [],
     );
+
     const payload = new Float32Array(uploads[0]?.buffer ?? new ArrayBuffer(0));
-    expect(payload[132 + 12]).toBe(9);
+    expect(Array.from(payload.slice(16, 19))).toEqual([0.25, -0.5, 0.75]);
   });
 
   it('writes temporal current/previous projection after the spot-light lanes', () => {

package/src/record/__tests__/typed-frame-graph-plan.unit.test.ts

@@ -19,6 +19,7 @@ const captureDescriptor = {
 
 type CaptureOverrides = {
   readonly target?: boolean;
+  readonly onSubmitted?: () => void;
   readonly descriptor?: {
     readonly format?: 'rgba16float' | 'rgba8unorm';
     readonly size?: { readonly width: number; readonly height: number };
@@ -51,7 +52,7 @@ function executeCapture(overrides: CaptureOverrides = {}) {
         usage: GPU_TEXTURE_USAGE_COPY_SRC,
         identity: overrides.identity ?? {
           graphGeneration: 7,
-          frameId: 12,
+          frameId: 13,
           textureIdentity: getTextureIdentity(texture),
         },
       },
@@ -74,7 +75,14 @@ function executeCapture(overrides: CaptureOverrides = {}) {
     errorRegistry: { fire: (error: unknown) => errors.push(error) },
     device: { queue: { submit: () => ok(undefined) } },
   } as never;
-  const submitted = executeCompiledFrameGraph(internals, frameState, {} as never, encoder);
+  const submitted = executeCompiledFrameGraph(
+    internals,
+    frameState,
+    {} as never,
+    encoder,
+    undefined,
+    overrides.onSubmitted === undefined ? undefined : { onSubmitted: overrides.onSubmitted },
+  );
   return { submitted, errors, copies };
 }
 
@@ -142,6 +150,17 @@ describe('typed frame graph feature plan authority', () => {
     expect(result.copies).toHaveLength(1);
   });
 
+  it('keeps the submit hook on the successful commit path', () => {
+    let calls = 0;
+    const result = executeCapture({
+      onSubmitted: () => {
+        calls += 1;
+      },
+    });
+    expect(result.submitted).toBe(true);
+    expect(calls).toBe(1);
+  });
+
   it.each([
     [
       'missing same-submit copy / untouched sentinel',