@forgeax/engine-render 0.1.29 → 0.1.31

package/src/prepare/__tests__/extended-lighting-capability.unit.test.ts

@@ -12,7 +12,7 @@ const device = {
     samplerAliasing: true,
   } as RhiCaps,
   limits: {
-    maxSampledTexturesPerShaderStage: 20,
+    maxSampledTexturesPerShaderStage: 21,
     maxTextureDimension2D: 4096,
     maxTextureArrayLayers: 32,
     maxUniformBuffersPerShaderStage: 12,
@@ -50,7 +50,7 @@ describe('extended lighting capability admission', () => {
     expect(deriveExtendedLightingCapability(limited)).toEqual({
       admitted: false,
       topology: 'extendedLighting',
-      reason: 'maxSampledTexturesPerShaderStage 16 < 20',
+      reason: 'maxSampledTexturesPerShaderStage 16 < 21',
     });
   });
 });

package/src/prepare/extended-lighting/resources.ts

@@ -19,13 +19,13 @@ export const COOKIE_SLICE_SIZE = 256;
 export const COOKIE_MATRIX_BYTES = 32 * 16 * Float32Array.BYTES_PER_ELEMENT;
 /**
  * Minimum per-stage sampled-texture limit for the shared PBR + extended-
- * lighting pipeline-layout topology. The current BGL closure reserves 18
- * sampled textures for the URP path and 20 for the HDRP/Probe path after the
+ * lighting pipeline-layout topology. The current BGL closure reserves 19
+ * sampled textures for the URP path and 21 for the HDRP/Probe path after the
  * material IBL and transmission injections; WebGPU validates this pipeline-
  * layout count even when a compiled shader variant does not read every
  * optional entry.
  */
-export const EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES = 20;
+export const EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES = 21;
 
 /**
  * Keep shader-variant selection and resource admission on one capability fact.

package/src/record/__tests__/main-pass-geometry.unit.test.ts

@@ -1,7 +1,9 @@
 import { describe, expect, it } from 'vitest';
+import type { DispatchEntry } from '../../render-system-extract';
 import {
   geometryRenderStateForPass,
   requestsStandardTransmissionVariant,
+  sameOpaqueTemporalDraw,
 } from '../main-pass-geometry';
 
 describe('geometry pass render state', () => {
@@ -70,3 +72,69 @@ describe('Standard transmission variant selection', () => {
     ).toBe(false);
   });
 });
+
+describe('temporal projection of multipass materials', () => {
+  const forward: DispatchEntry = {
+    entityIndex: 0,
+    materialHandle: 1,
+    renderableIndex: 0,
+    passIndex: 0,
+    queue: 2000,
+    layer: 0,
+    tags: { LightMode: 'Forward' },
+    renderState: { cullMode: 'back' },
+    defines: undefined,
+    vertexEntry: 'vs_main',
+    fragmentEntry: 'fs_forward',
+    materialShaderId: 'forgeax::default-standard-pbr',
+    paramSnapshot: undefined,
+  };
+  const deferred = {
+    ...forward,
+    passIndex: 1,
+    tags: { LightMode: 'Deferred' },
+    fragmentEntry: 'fs_gbuffer',
+  };
+  it('projects identical opaque Forward and Deferred geometry only once', () => {
+    expect(sameOpaqueTemporalDraw(forward, deferred)).toBe(true);
+    const surface = {
+      ...forward,
+      materialShaderId: 'generated::surface',
+      tags: {
+        LightMode: 'Forward',
+        SurfaceKind: 'standard',
+        SurfaceModule: 'author::surface',
+      },
+    };
+    expect(
+      sameOpaqueTemporalDraw(surface, {
+        ...surface,
+        tags: { ...surface.tags, LightMode: 'Deferred' },
+      }),
+    ).toBe(true);
+    const fullCustom = { ...forward, materialShaderId: 'custom::full' };
+    expect(sameOpaqueTemporalDraw(fullCustom, fullCustom)).toBe(false);
+  });
+  it('preserves different shader, culling, stencil and blending semantics', () => {
+    expect(sameOpaqueTemporalDraw(forward, { ...deferred, materialShaderId: 'other' })).toBe(false);
+    expect(
+      sameOpaqueTemporalDraw(forward, { ...deferred, renderState: { cullMode: 'front' } }),
+    ).toBe(false);
+    expect(sameOpaqueTemporalDraw(forward, { ...deferred, stencilReference: 1 })).toBe(false);
+    const blended = {
+      ...forward,
+      renderState: {
+        blend: {
+          color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha' },
+          alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
+        },
+      },
+    } as const;
+    expect(sameOpaqueTemporalDraw(blended, blended)).toBe(false);
+    const stencil = {
+      ...forward,
+      renderState: { stencil: { passOp: 'increment-clamp' } },
+    } as const;
+    expect(sameOpaqueTemporalDraw(stencil, stencil)).toBe(false);
+  });
+});

package/src/record/__tests__/material-bg-cache.unit.test.ts

@@ -34,6 +34,51 @@ describe('material bind-group assembly cache', () => {
     expect(
       isMaterialBgAssemblyCacheHit(cached, material, materialBgl, newBuffer, skylightResources, 7),
     ).toBe(false);
+    expect(
+      isMaterialBgAssemblyCacheHit(
+        cached,
+        material,
+        materialBgl,
+        oldBuffer,
+        { ...skylightResources, skylightPrefilterView: {} as TextureView },
+        7,
+      ),
+    ).toBe(false);
+    const sceneCached = { ...cached, sceneMaterialBuffer: oldBuffer };
+    expect(
+      isMaterialBgAssemblyCacheHit(
+        sceneCached,
+        material,
+        materialBgl,
+        oldBuffer,
+        skylightResources,
+        7,
+        undefined,
+        oldBuffer,
+      ),
+    ).toBe(true);
+    expect(
+      isMaterialBgAssemblyCacheHit(
+        sceneCached,
+        material,
+        materialBgl,
+        oldBuffer,
+        skylightResources,
+        7,
+        undefined,
+        newBuffer,
+      ),
+    ).toBe(false);
+    expect(
+      isMaterialBgAssemblyCacheHit(
+        sceneCached,
+        material,
+        materialBgl,
+        oldBuffer,
+        skylightResources,
+        7,
+      ),
+    ).toBe(false);
     expect(
       isMaterialBgAssemblyCacheHit(cached, material, materialBgl, oldBuffer, skylightResources, 8),
     ).toBe(false);

package/src/record/__tests__/material-slot-plan.unit.test.ts

@@ -52,6 +52,15 @@ describe('material slot plan', () => {
     });
   });
 
+  it('separates per-object probe/pass bindings while interning the same resource class', () => {
+    const material = {};
+    expect(
+      buildMaterialSlotPlan([[material], [material], [material]], (_, owner) =>
+        owner === 1 ? 'probe:1' : 'probe:0',
+      ),
+    ).toEqual({ slotIndices: [[0], [1], [0]], slots: [material, material], slotOwners: [0, 1] });
+  });
+
   it('does not merge equal-looking snapshots with distinct identities', () => {
     expect(buildMaterialSlotPlan([[{}], [{}]])).toMatchObject({
       slotIndices: [[0], [1]],

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

@@ -1,7 +1,10 @@
 import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
 import { describe, expect, it } from 'vitest';
 import { makeZeroCameraFallbackSnapshot, type ValidatedRenderable } from '../frame-snapshot';
-import { prepareRecoveryPipelineReadiness } from '../recovery-pipeline';
+import {
+  createRecoveryColdWorkGuard,
+  prepareRecoveryPipelineReadiness,
+} from '../recovery-pipeline';
 import type { PipelineState, RenderSystemInternals } from '../render-context';
 
 function probeRenderable(probe: boolean): ValidatedRenderable {
@@ -94,4 +97,47 @@ describe('recovery prepared pipeline cache', () => {
     expect(standardPbr?.shader.variantSet).toContain('REFLECTION_FALLBACK_AVAILABLE=true');
     expect(standardPbr?.attachments.colorFormats).toEqual(['rgba16float', 'rgba16float']);
   });
+  it('allows explicit candidate uploads between recovery publication and the first draw', () => {
+    const guard = createRecoveryColdWorkGuard();
+    guard.arm();
+    expect(() => guard.noteUploadColdWork()).not.toThrow();
+  });
+
+  it('keeps the first-submit assertion across a skipped draw and releases its recording scope', () => {
+    const guard = createRecoveryColdWorkGuard();
+    guard.arm();
+    guard.beginFrame();
+    guard.endFrame();
+    expect(() => guard.noteUploadColdWork()).not.toThrow();
+    guard.beginFrame();
+    expect(() => guard.noteUploadColdWork()).toThrow(/cold upload/);
+    guard.endFrame();
+    expect(() => guard.noteUploadColdWork()).not.toThrow();
+  });
+
+  it('accepts a prepared candidate with no first-frame cold work', () => {
+    const guard = createRecoveryColdWorkGuard();
+
+    guard.arm();
+    guard.beginFrame();
+    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();
+    guard.beginFrame();
+    expect(() => note(guard)).toThrow(/recovery first frame performed cold/);
+  });
 });

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

@@ -87,7 +87,8 @@ describe('sprite Standard material ABI', () => {
       binding: 23,
       resource: { kind: 'textureView' },
     });
-    expect(merged).toHaveLength(24);
+    expect(merged).toHaveLength(25);
+    expect(merged.find((entry) => entry.binding === 47)?.resource.kind).toBe('textureView');
 
     const complete = [
       ...merged,
@@ -96,8 +97,11 @@ describe('sprite Standard material ABI', () => {
         resource: { kind: 'buffer' as const, value: { buffer: {} as Buffer } },
       },
     ];
-    expect(complete).toHaveLength(25);
-    expect(complete[24]).toMatchObject({ binding: 46, resource: { kind: 'buffer' } });
+    expect(complete).toHaveLength(26);
+    expect(complete.find((entry) => entry.binding === 46)).toMatchObject({
+      binding: 46,
+      resource: { kind: 'buffer' },
+    });
 
     const backdrop = {} as TextureView;
     const active = assembleMaterialWithSkylightEntries(

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

@@ -84,6 +84,8 @@ function temporalView(): TemporalView {
     viewId: '0:1:0',
     historyVersion: 0,
     temporalFrameIndex: 1,
+    internalWidth: 4,
+    internalHeight: 4,
     historyValid: true,
     resetReason: undefined,
     currentJitterUv: [0, 0],

package/src/record/frame-lighting.ts

@@ -58,7 +58,7 @@ import {
   ShadowAtlas,
 } from '../shadow-atlas';
 import { getOrCreateSsaoBuffers } from '../ssao-buffers';
-import { getSsaoParameters } from '../ssao-config';
+import { getSsaoParameters, SSAO_SAMPLE_COUNTS } from '../ssao-config';
 // extendedLighting keeps Spot modifier factors on the existing light record
 // path; no additional render pass or submit owner is introduced.
 import type { BindGroupCounts, RenderFrameState } from './frame-snapshot';
@@ -1128,6 +1128,7 @@ export function writeHdrpClusterAndSsaoBuffers(
     profilePhase,
     'record/scene-state/hdrp-cluster/buffer-upload',
     (): Result<void, RenderError> => {
+      if (frameState.installedPipelineConfig?.ssao?.enabled !== true) return ok(undefined);
       const ssaoBufs = getOrCreateSsaoBuffers(internals);
       if (ssaoBufs === null) return ok(undefined);
       const sProj = computeProjectionMatrix(camera);
@@ -1152,6 +1153,7 @@ export function writeHdrpClusterAndSsaoBuffers(
       ssaoUniformPayload[48] = parameters.intensity;
       ssaoUniformPayload[49] = parameters.radius;
       ssaoUniformPayload[50] = parameters.bias;
+      ssaoUniformPayload[51] = SSAO_SAMPLE_COUNTS[parameters.quality];
 
       const ssaoUniformRes = internals.device.queue.writeBuffer(
         ssaoBufs.uniformBuffer,

package/src/record/frame-snapshot.ts

@@ -107,6 +107,7 @@ export interface MaterialBgAssemblyCacheEntry {
   readonly materialBgl: BindGroupLayout;
   /** Buffer identity changes when the shared material capacity grows. */
   readonly materialBuffer: Buffer;
+  readonly sceneMaterialBuffer?: Buffer;
   readonly skylightResources: SkylightBindGroupResources;
   readonly bindGroup: BindGroup;
 }
@@ -234,10 +235,17 @@ export function validateGraphTargetCaptureReadback(input: {
   if (!allowZero && bytes.every((value) => value === 0)) {
     return { ok: false, code: 'capture-readback-empty' };
   }
-  for (let index = 0; index + 1 < bytes.length; index += 2) {
-    const exponent = ((bytes[index + 1] ?? 0) >>> 2) & 0x1f;
-    if (exponent === 0x1f) return { ok: false, code: 'capture-readback-non-finite' };
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let index = 0;
+  // Inspect both half-float exponents per word. DataView also preserves
+  // little-endian capture semantics for unaligned slices and host byte orders.
+  for (; index + 3 < bytes.byteLength; index += 4) {
+    const word = view.getUint32(index, true);
+    if ((word & 0x7c00) === 0x7c00 || (word & 0x7c000000) === 0x7c000000)
+      return { ok: false, code: 'capture-readback-non-finite' };
   }
+  if (index + 1 < bytes.byteLength && (view.getUint16(index, true) & 0x7c00) === 0x7c00)
+    return { ok: false, code: 'capture-readback-non-finite' };
   return { ok: true };
 }
 
@@ -658,14 +666,8 @@ export interface RenderFrameState {
   readonly materialBgShared: Map<string, WeakMap<object, unknown>>;
   /** Cross-frame fast path for fully-resident, immutable material snapshots. */
   readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
-  /**
-   * feat-20260622-handle-to-id-allocator-elimination M1 / w2: singleton
-   * material bind group cache (D-6). Single flat Map<variant, BindGroup>
-   * for the one true singleton in production: shadow-material-singleton.
-   * shadow-instances-singleton is a test fixture fiction (research F3);
-   * no second singleton field is needed.
-   */
-  readonly singletonMaterialCache: Map<string, BindGroup>;
+  /** Opaque shadow fallback bindings follow physical resources across scene replacement. */
+  shadowMaterialBindGroups: WeakMap<object, unknown>;
   /**
    * Post-process bind group cache: nested WeakMap chain root shared by the
    * built-in bloom (bright / blur-H / blur-V / composite), FXAA, and HDRP SSAO