@forgeax/engine-render 0.1.31 → 0.1.33

package/src/__tests__/prepared-graphics-lifecycle.unit.test.ts

@@ -1,6 +1,7 @@
 import type { RhiCaps } from '@forgeax/engine-rhi';
 import { err, ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { RenderFeaturePreparationFailedError } from '../errors/render';
 import {
   createRenderFeatureHost,
   runRenderFeatureFrame,
@@ -136,3 +137,88 @@ describe('prepared graphics lifecycle ownership', () => {
     expect(releases).toBe(2);
   });
 });
+
+for (const readyFirst of [true, false]) {
+  it(`retains partial resolver allocations through pending pipelines (ready pass: ${readyFirst})`, () => {
+    let releases = 0;
+    const lease = {
+      release: () => {
+        releases += 1;
+        return ok(undefined);
+      },
+    };
+    const feature: RenderFeature<undefined> = {
+      identity: 'pending.material',
+      extract: () => ok(undefined),
+      plan: () =>
+        ok({
+          resources: ['ready', 'pending'].flatMap((name) => [
+            {
+              kind: 'graphics-program' as const,
+              name,
+              program: {
+                shader: name,
+                vertexLayout: 'none',
+                colorFormats: ['rgba8unorm' as const],
+              },
+            },
+            {
+              kind: 'graphics-bindings' as const,
+              name: `${name}-bindings`,
+              program: name,
+              values: {},
+            },
+          ]),
+          passes: (readyFirst ? ['ready', 'pending'] : ['pending']).map((name) => ({
+            kind: 'raster' as const,
+            name,
+            colorAttachments: [
+              { target: 'swapchain', loadOp: 'load' as const, storeOp: 'store' as const },
+            ],
+            draws: [
+              {
+                vertexLayout: 'none' as const,
+                vertexData: [],
+                program: name,
+                bindings: [`${name}-bindings`],
+                draw: { kind: 'draw' as const, vertexCount: 3, instanceCount: 1 },
+              },
+            ],
+          })),
+        }),
+    };
+    const host = createRenderFeatureHost([feature]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps,
+      createPreparedGraphicsResolver: (input) => ({
+        leases: [lease],
+        release: lease.release,
+        resolve: (ref) => {
+          const item = input.lookup(ref);
+          if (item?.name === 'pending')
+            return err(
+              new RenderFeaturePreparationFailedError(
+                feature.identity,
+                0,
+                'prepare',
+                'pipeline',
+                'pending',
+                'pipeline-pending',
+                'next-frame',
+              ),
+            );
+          return ok({ kind: ref.kind, reference: ref, handle: {} } as never);
+        },
+      }),
+    });
+    expect(result.errors, JSON.stringify(result.errors)).toEqual([]);
+    expect(releases).toBe(0);
+    expect(result.preparedResourceBatches).toHaveLength(1);
+    host.markPreparedGraphicsSubmitted(result.preparedResourceBatches);
+    host.retirePreparedGraphics(result.preparedResourceBatches);
+    expect(releases).toBe(1);
+  });
+}

package/src/__tests__/public-surface.test-d.ts

@@ -2,6 +2,7 @@ import type {
   FrameObservationRequest,
   FrameReceipt,
   RenderError as PublicRenderError,
+  SunCardinalityError as PublicSunCardinalityError,
   ReflectionProbeInspection,
   ReflectionProbeSelectionInspection,
   RendererState,
@@ -65,6 +66,13 @@ const ssrInspection: SsrSpatialInspection = inspection.ssr;
 void ssrInspection;
 type IntentError = Extract<PublicRenderError, { readonly code: 'render-intent-invalid' }>;
 expectTypeOf<IntentError['detail']>().toEqualTypeOf<RenderIntentInvalidDetail>();
+type PublicSunCardinalityCode = Extract<PublicRenderError['code'], 'sun-cardinality'>;
+expectTypeOf<PublicSunCardinalityCode>().toEqualTypeOf<'sun-cardinality'>();
+expectTypeOf<PublicSunCardinalityError['code']>().toEqualTypeOf<'sun-cardinality'>();
+expectTypeOf<PublicSunCardinalityError['detail']>().toEqualTypeOf<{
+  readonly field: 'sun';
+  readonly value: number;
+}>();
 const backendKind: RenderInspection['capabilities']['backendKind'] =
   inspection.capabilities.backendKind;
 void backendKind;

package/src/__tests__/render-error-code-owner.test-d.ts

@@ -39,6 +39,7 @@ const expectedCodes = [
   'dynamic-resolution-invalid-parameter',
   'dynamic-resolution-requires-taa',
   'dynamic-resolution-timing-unavailable',
+  'motion-blur-invalid-params',
   'shadow-invalid-config',
   'equirect-projection-failed',
   'standard-light-budget-exceeded',
@@ -63,6 +64,7 @@ const expectedCodes = [
   'render-feature-draw-recording-failed',
   'environment-source-conflict',
   'fog-cardinality',
+  'sun-cardinality',
   'taa-caps-insufficient',
   'environment-generation-failed',
   'atmosphere-invalid-parameter',

package/src/__tests__/render-feature-error-reporting.unit.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import {
+  PENDING_RENDER_FEATURE_ERROR_REPORT_INTERVAL_FRAMES,
+  shouldReportPendingRenderFeatureError,
+} from '../features/error-reporting.js';
+
+describe('pending render-feature error reporting', () => {
+  it('reports the first failure, suppresses the hot-loop, and reopens the cooldown', () => {
+    const lastReportedFrame = new Map<string, number>();
+    expect(shouldReportPendingRenderFeatureError(lastReportedFrame, 'feature\0plan', 10)).toBe(
+      true,
+    );
+    expect(shouldReportPendingRenderFeatureError(lastReportedFrame, 'feature\0plan', 11)).toBe(
+      false,
+    );
+    expect(
+      shouldReportPendingRenderFeatureError(
+        lastReportedFrame,
+        'feature\0plan',
+        10 + PENDING_RENDER_FEATURE_ERROR_REPORT_INTERVAL_FRAMES,
+      ),
+    ).toBe(true);
+  });
+});

package/src/__tests__/render-feature-stage-fault-recovery.unit.test.ts

@@ -89,6 +89,29 @@ function frame(host: RenderFeatureHost, frameNumber: number) {
 }
 
 describe('RenderFeature stage fault recovery lifecycle', () => {
+  it('retains the original exception when a feature stage throws', () => {
+    const cause = new TypeError('feature plan exploded');
+    const host = createRenderFeatureHost(
+      [
+        {
+          identity: 'synthetic.m10.throwing',
+          extract: () => ok({ ready: true }),
+          plan: () => {
+            throw cause;
+          },
+        },
+      ],
+      caps,
+    ).unwrap();
+
+    const result = frame(host, 1);
+    expect(result.errors[0]).toMatchObject({
+      code: 'render-feature-stage-failed',
+      detail: { featureIdentity: 'synthetic.m10.throwing', cause },
+    });
+    expect(host.diagnostics()[0]?.latestError).toMatchObject({ detail: { cause } });
+  });
+
   it.each<Fault>([
     'create',
     'prepared-resource',

package/src/__tests__/render-scene-temporal-retry.unit.test.ts

@@ -130,4 +130,35 @@ describe('RenderScene temporal retry boundary', () => {
       instanceCollections.dispose();
     }
   });
+
+  it('keeps instance motion valid when stable generations reorder', () => {
+    const instanceCollections = new InstanceCollectionStore();
+    const collection = instanceCollections.create({ transforms: matrices(2, 1) }).unwrap();
+    const initialInstances = instanceCollections.snapshot(collection.collectionId).unwrap();
+    instanceCollections
+      .replace(
+        collection.collectionId,
+        matrices(2, 9),
+        new Uint32Array([
+          initialInstances.generations[1] ?? 0,
+          initialInstances.generations[0] ?? 0,
+        ]),
+      )
+      .unwrap();
+    const reorderedInstances = instanceCollections.snapshot(collection.collectionId).unwrap();
+    const scene = new RenderScene();
+    scene.setTemporalTracking(true);
+    try {
+      scene.apply([updateSnapshot(snapshot(7, 1, initialInstances))]);
+      submit(scene, 7);
+      scene.apply([updateInstances(snapshot(7, 1, reorderedInstances))]);
+
+      const temporal = scene.temporalSnapshotBySlot(0);
+      expect(temporal?.motionValid).toBe(true);
+      expect(temporal?.previousInstances?.generations).toEqual(initialInstances.generations);
+      expect(temporal?.previousInstances?.transforms).toEqual(initialInstances.transforms);
+    } finally {
+      instanceCollections.dispose();
+    }
+  });
 });

package/src/__tests__/renderer-frame-transaction.integration.test.ts

@@ -87,7 +87,8 @@ function temporalResolveFrame(
       bloom: 'off',
       bloomThreshold: 1,
       bloomIntensity: 1,
-      bloomBlurRadius: 1,
+      bloomSoftKnee: 0.5,
+      bloomScatter: 0.7,
       clearColor: [0, 0, 0, 1],
       temporal: frameState.lastSuccessfulTemporalView,
     },
@@ -1147,6 +1148,7 @@ describe('renderer successful-submit transaction', () => {
       height: 4,
       frameIndex: 6,
       historyValid: true,
+      sampleTimeSeconds: 1,
     });
     const frameState = {
       temporalGpuState: undefined,
@@ -1160,6 +1162,7 @@ describe('renderer successful-submit transaction', () => {
           height: 4,
           frameIndex: 6,
           historyValid: true,
+          sampleTimeSeconds: 1.016,
         }),
       },
       environmentGeneration,
@@ -1244,6 +1247,7 @@ describe('renderer successful-submit transaction', () => {
     expect(active.valid).toBe(true);
     expect(active.readIndex).toBe(1);
     expect(frameState.lastSuccessfulTemporalView).toBe(lastSuccessfulTemporalView);
+    expect(frameState.lastSuccessfulTemporalView.sampleTimeSeconds).toBe(1);
     expect(environmentLifecycle.inspect().activeSignature).toBe(activeEnvironment.signature);
     expect(environmentLifecycle.inspect().lkgSignature).toBe(activeEnvironment.signature);
     frameState.environmentGeneration = environmentLifecycle
@@ -1257,6 +1261,7 @@ describe('renderer successful-submit transaction', () => {
         height: 8,
         frameIndex: 7,
         historyValid: true,
+        sampleTimeSeconds: 1.016,
       }),
     };
     const retryFrame = temporalResolveFrame(device, scope, frameState, {});
@@ -1273,6 +1278,7 @@ describe('renderer successful-submit transaction', () => {
     expect(gpuCommitAfterSubmit).toEqual([1]);
     expect(frameState.activeTemporalGpuState).not.toBe(active);
     expect(frameState.successfulTemporalFrameIndex).toBe(8);
+    expect(frameState.lastSuccessfulTemporalView?.sampleTimeSeconds).toBe(1.016);
     expect(frameState.temporalGpuState).toBeUndefined();
     expect(frameState.retiringTemporalGpuStates.size).toBe(1);
     expect(publishEnvironment).toHaveBeenCalledTimes(1);

package/src/__tests__/shader-manifest-fixture.ts

@@ -43,14 +43,14 @@ const entries: readonly FixtureEntry[] = [
     bindings: '[]',
   },
   {
-    hash: 'fixture-bloom-bright',
-    wgsl: '// fixture marker: BloomBrightParams\n',
+    hash: 'fixture-bloom-downsample',
+    wgsl: '// fixture marker: BloomDownsampleParams\n',
     glsl: '',
     bindings: '[]',
   },
   {
-    hash: 'fixture-bloom-blur',
-    wgsl: '// fixture marker: BloomBlurParams\n',
+    hash: 'fixture-bloom-upsample',
+    wgsl: '// fixture marker: BloomUpsampleParams\n',
     glsl: '',
     bindings: '[]',
   },

package/src/__tests__/skinned-shadow-caster.test.ts

@@ -60,6 +60,8 @@ describe('skinned shadow caster', () => {
     expect(shader).toContain('discard;');
     expect(shader).toContain('@group(2) @binding(1)');
     expect(shader).toContain('let skinMatrix = palette[');
+    expect(shader).toContain('materialIndex = u32(meshes[meshIndex].temporal.w);');
+    expect(shader).not.toContain('bitcast<u32>(meshes[meshIndex].temporal.w)');
     expect(shader).toContain('@location(13) color : vec4<f32>');
     expect(shader).toContain('out.color = in.color;');
     expect(record).toContain('entry.source.skin.byteOffset');

package/src/__tests__/standard-lighting-write.unit.test.ts

@@ -41,7 +41,8 @@ function camera(): CameraSnapshot {
     bloom: 'off',
     bloomThreshold: 1,
     bloomIntensity: 1,
-    bloomBlurRadius: 4,
+    bloomSoftKnee: 0.5,
+    bloomScatter: 0.7,
     clearColor: [0, 0, 0, 1],
   };
 }

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

@@ -31,7 +31,7 @@ function topology(): RenderPipelineTopology {
       storageFormat: 'bgra8unorm',
       viewFormat: 'bgra8unorm-srgb',
     },
-    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'on' },
+    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'on', bloomIntensity: 1 },
     shadow: {
       directional: { mapSize: 64, cascadeCount: 1 },
       spotMapSize: 64,

package/src/__tests__/standard-pipeline.integration.test.ts

@@ -35,10 +35,15 @@ const dualViewProfile: SurfaceProfile = {
   hasDisplayEndpoint: true,
 };
 
+type TopologyOverrides = Omit<Partial<RenderPipelineTopology>, 'camera'> & {
+  readonly camera?: Partial<RenderPipelineTopology['camera']>;
+};
+
 function topology(
   profile: StandardProfile,
-  overrides: Partial<RenderPipelineTopology> = {},
+  overrides: TopologyOverrides = {},
 ): RenderPipelineTopology {
+  const { camera: cameraOverride, ...rest } = overrides;
   return {
     pipelineId: STANDARD_PIPELINE_ID,
     standardProfile: profile,
@@ -49,7 +54,13 @@ function topology(
       storageFormat: 'bgra8unorm',
       viewFormat: 'bgra8unorm-srgb',
     },
-    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'on' },
+    camera: {
+      tonemap: 'aces-filmic',
+      antialias: 'fxaa',
+      bloom: 'on',
+      bloomIntensity: 1,
+      ...cameraOverride,
+    },
     shadow: {
       directional: { mapSize: 64, cascadeCount: 1 },
       spotMapSize: 64,
@@ -65,7 +76,7 @@ function topology(
     },
     featureTopologySignature: 'none',
     gpuDrivenTopologySignature: '',
-    ...overrides,
+    ...rest,
   };
 }
 
@@ -109,7 +120,7 @@ function standardLightingFor(resolvedTopology: RenderPipelineTopology) {
   return standardLighting;
 }
 
-async function build(profile: StandardProfile, overrides?: Partial<RenderPipelineTopology>) {
+async function build(profile: StandardProfile, overrides?: TopologyOverrides) {
   const graph = new RenderGraphBuilder<RenderPipelineFrame>();
   const resolvedTopology = topology(profile, overrides);
   const histogram = graph.createBuffer('standard-auto-exposure-histogram', { size: 1024 });
@@ -232,7 +243,7 @@ function importedTaaHistory(graph: RenderGraphBuilder<RenderPipelineFrame>) {
   };
 }
 
-async function buildTaa(profile: StandardProfile, overrides?: Partial<RenderPipelineTopology>) {
+async function buildTaa(profile: StandardProfile, overrides?: TopologyOverrides) {
   const graph = new RenderGraphBuilder<RenderPipelineFrame>();
   const history = importedTaaHistory(graph);
   const resolvedTopology = topology(profile, overrides);
@@ -542,9 +553,8 @@ describe('forgeax::standard graph', () => {
     expect(result.ok).toBe(true);
     if (!result.ok) return;
     const names = result.value.inspect().passes.map((pass) => pass.name);
-    expect(names).not.toContain('bloom-bright');
-    expect(names).not.toContain('bloom-blur-h');
-    expect(names).not.toContain('bloom-blur-v');
+    expect(names.some((name) => name.startsWith('bloom-downsample-'))).toBe(false);
+    expect(names.some((name) => name.startsWith('bloom-upsample-'))).toBe(false);
     expect(names).not.toContain('bloom-composite');
     expect(names).toContain('taa-resolve');
     expect(names).toContain('output-transform');

package/src/__tests__/temporal-reset-matrix.unit.test.ts

@@ -37,6 +37,16 @@ describe('TemporalView reset matrix', () => {
     expect(resolveTemporalReset(previous, next)).toBeUndefined();
   });
 
+  it('applies camera reset reasons to motion-blur-only off views', () => {
+    const previous = createTemporalView({ ...base().input, antialias: 'none' });
+    const next = createTemporalView({
+      ...previous.input,
+      antialias: 'none',
+      viewIdentity: 'secondary',
+    });
+    expect(resolveTemporalReset(previous, next)).toBe('view-switch');
+  });
+
   it('treats an explicit off commit as a first-frame boundary when TAA resumes', () => {
     const previous = base();
     const off = createTemporalView({

package/src/__tests__/temporal-view.unit.test.ts

@@ -130,7 +130,8 @@ describe('TemporalView v1', () => {
       bloom: 'disabled',
       bloomThreshold: 1,
       bloomIntensity: 0,
-      bloomBlurRadius: 0,
+      bloomSoftKnee: 0.5,
+      bloomScatter: 0.7,
       clearColor: [0, 0, 0, 1] as const,
     } as unknown as CameraSnapshot;
     const light = {

package/src/__tests__/typed-pipeline-topology.unit.test.ts

@@ -32,6 +32,10 @@ import { standardTemporalPostOrder } from '../temporal/standard-scene-data';
 
 let device: RhiDevice;
 
+type TopologyOverrides = Omit<Partial<RenderPipelineTopology>, 'camera'> & {
+  readonly camera?: Partial<RenderPipelineTopology['camera']>;
+};
+
 beforeAll(async () => {
   const adapter = await rhi.requestAdapter();
   if (!adapter.ok) throw adapter.error;
@@ -42,8 +46,9 @@ beforeAll(async () => {
 
 function topology(
   pipelineId: 'forgeax::standard',
-  overrides: Partial<RenderPipelineTopology> = {},
+  overrides: TopologyOverrides = {},
 ): RenderPipelineTopology {
+  const { camera: cameraOverride, ...rest } = overrides;
   return {
     pipelineId,
     config: undefined,
@@ -53,7 +58,13 @@ function topology(
       storageFormat: 'bgra8unorm',
       viewFormat: 'bgra8unorm-srgb',
     },
-    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'on' },
+    camera: {
+      tonemap: 'aces-filmic',
+      antialias: 'fxaa',
+      bloom: 'on',
+      bloomIntensity: 1,
+      ...cameraOverride,
+    },
     shadow: {
       directional: { mapSize: 1024, cascadeCount: 4 },
       spotMapSize: 1024,
@@ -69,7 +80,7 @@ function topology(
     },
     featureTopologySignature: 'none',
     gpuDrivenTopologySignature: '',
-    ...overrides,
+    ...rest,
   };
 }
 
@@ -877,7 +888,12 @@ describe('typed built-in pipeline topology', () => {
 
   it('keeps zero-shutter Motion Blur free of temporal target and passes', () => {
     expect(
-      isMotionBlurTemporalDemand({ shutterAngle: 0, maxRadiusPixels: 32, sampleCount: 8 }),
+      isMotionBlurTemporalDemand({
+        shutterAngle: 0,
+        maxRadiusPixels: 32,
+        sampleCount: 8,
+        targetFps: 60,
+      }),
     ).toBe(false);
     const compiled = compile(
       standardPipeline,

package/src/__tests__/volume-optics-oracle.unit.test.ts

@@ -42,7 +42,9 @@ describe('volumetric optics CPU oracle', () => {
 
   it('converts the shared integrated-light basis once before normalized HG', () => {
     expect(integrateShader).toContain('const VOLUME_LIGHT_PHASE_SCALE : f32 = FOUR_PI;');
-    expect(integrateShader).toContain('phase *\n        VOLUME_LIGHT_PHASE_SCALE *');
+    expect(integrateShader.match(/phase\s*\*\s*VOLUME_LIGHT_PHASE_SCALE\s*\*/g) ?? []).toHaveLength(
+      1,
+    );
   });
 
   it('keeps empty density at identity transmittance', () => {