@forgeax/engine-render 0.1.31 → 0.1.33

package/src/features/host.ts

@@ -17,7 +17,7 @@ import type {
   PreparedGraphicsResolver,
   PreparedGraphicsResourceLease,
 } from '../prepare/prepared-graphics-resolver';
-import type { SceneDataTarget } from '../temporal/scene-data';
+import { isSceneDataTarget, type SceneDataTarget } from '../temporal/scene-data';
 import { createSceneDataCatalog, type SceneDataCatalog } from '../temporal/scene-data-catalog';
 import {
   cloneRenderFeaturePlanSignatureSnapshot,
@@ -134,6 +134,8 @@ export interface RenderFeatureFrameInput {
   readonly worlds: readonly import('@forgeax/engine-ecs').World[];
   readonly owner: number;
   readonly frameNumber: number;
+  /** Physical render extent for bounded feature dispatch sizing. */
+  readonly frameSize?: { readonly width: number; readonly height: number };
   readonly visibilitySnapshots?: readonly RenderFeatureWorldVisibilitySnapshot[];
   readonly hiddenEntityReports?: readonly RenderFeatureHiddenEntityReport[];
   /** Active-pipeline logical targets available to producer-owned features. */
@@ -412,7 +414,7 @@ function asFeatureError(
   if (error instanceof Error && typeof (error as Partial<RenderError>).code === 'string') {
     return error as RenderError;
   }
-  return new RenderFeatureStageFailedError(identity, order, stage, 'next-frame');
+  return new RenderFeatureStageFailedError(identity, order, stage, 'next-frame', error);
 }
 
 function featureErrorForSlot(slot: FeatureSlot, error: RenderError): RenderError {
@@ -431,6 +433,7 @@ function featureErrorForSlot(slot: FeatureSlot, error: RenderError): RenderError
             slot.order,
             'plan',
             'next-frame',
+            error,
           );
     default:
       return new RenderFeatureStageFailedError(
@@ -438,6 +441,7 @@ function featureErrorForSlot(slot: FeatureSlot, error: RenderError): RenderError
         slot.order,
         'plan',
         'next-frame',
+        error,
       );
   }
 }
@@ -467,6 +471,7 @@ function errorDescriptor(error: RenderError): RenderFeatureErrorDescriptor {
           order: -1,
           stage: 'plan',
           recovery: 'next-frame',
+          cause: error,
         },
       };
   }
@@ -606,14 +611,17 @@ function preparePlanResources(
           : targetHandle(resource.logicalTarget, targets);
       if (
         resource.logicalTarget !== undefined &&
-        (logical === undefined || !isRenderFeatureTargetHandle(logical))
+        (logical === undefined ||
+          (typeof logical !== 'string' &&
+            !isRenderFeatureTargetHandle(logical) &&
+            !isSceneDataTarget(logical)))
       ) {
         return err(planFailure(slot));
       }
       const prepared = gpu.prepareTextureView(
         resource.name,
-        resource.resource.value as TextureView,
-        logical === undefined || !isRenderFeatureTargetHandle(logical) ? undefined : logical,
+        resource.resource.value as TextureView | undefined,
+        logical === undefined ? undefined : logical,
       );
       if (!prepared.ok) return prepared;
       preparedGpuResources.set(resource.name, {
@@ -1429,7 +1437,10 @@ export function runRenderFeatureFrame(
       () =>
         feature.plan(extracted.value, {
           caps: input.caps,
-          frame: { frameNumber: input.frameNumber },
+          frame: {
+            frameNumber: input.frameNumber,
+            ...(input.frameSize === undefined ? {} : input.frameSize),
+          },
           generation: transaction.generation,
           targets,
           sceneData,
@@ -1499,9 +1510,9 @@ export function runRenderFeatureFrame(
       resolver === undefined
         ? undefined
         : (descriptor: import('./prepared-graphics').RenderFeatureGraphicsPassDescriptor) => {
-            const resolved = resolveGraphicsSnapshot(resolver, descriptor, transaction.generation);
-            if (!resolved.ok) resolver.release();
-            return resolved;
+            // A pending pass can be skipped while earlier passes remain usable.
+            // Keep their shared resolver leases alive until submission retires them.
+            return resolveGraphicsSnapshot(resolver, descriptor, transaction.generation);
           };
     const releaseResolver = (): void => {
       if (resolver !== undefined) resolver.release();
@@ -1529,9 +1540,11 @@ export function runRenderFeatureFrame(
       host.setStatus(identity, 'failed', slot.latestError);
       continue;
     }
-    const graphicsLeases = projected.value.passes.flatMap(
-      (pass) => pass.resolvedGraphics?.leases ?? [],
-    );
+    // Include partial allocations from skipped pending passes, even when no pass
+    // completed. Fatal projection failures release the resolver above instead.
+    const graphicsLeases =
+      resolver?.leases ??
+      projected.value.passes.flatMap((pass) => pass.resolvedGraphics?.leases ?? []);
     if (graphicsLeases.length > 0) requiresPreparedResourceKey = true;
     const leases = [...new Set(graphicsLeases), ...(gpu?.retireUntouched() ?? [])];
     const retained = host.retainPreparedGraphics(identity, leases);
@@ -1545,7 +1558,7 @@ export function runRenderFeatureFrame(
     if (feature.onFrameSubmitted !== undefined) {
       submissionSensitivePlans.add(plannedFrame);
       submissionAcknowledgments.set(plannedFrame, () =>
-        feature.onFrameSubmitted?.(extracted.value),
+        feature.onFrameSubmitted?.(extracted.value, projected.value),
       );
     }
     plans.push(plannedFrame);

package/src/features/motion-blur/__tests__/motion-blur-feature.unit.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 import { SCENE_DATA_TEMPORAL_V1_SCHEMA } from '../../../temporal/scene-data';
 import { createSceneDataCatalog } from '../../../temporal/scene-data-catalog';
 import { freezeRenderFeaturePlan } from '../../plan';
-import { planMotionBlur } from '../motion-blur-feature';
+import { MOTION_BLUR_COMPUTE_WGSL, planMotionBlur } from '../motion-blur-feature';
 import { DEFAULT_MOTION_BLUR_PARAMS } from '../motion-blur-params';
 
 const caps = {
@@ -64,4 +64,114 @@ describe('Motion Blur feature plan', () => {
     expect(pass.sampledTargets).not.toContain('motion-depth');
     expect(catalog.schema).toBe(SCENE_DATA_TEMPORAL_V1_SCHEMA);
   });
+
+  it('selects one tile summary and one fused reconstruction on compute-capable targets', () => {
+    const computeCaps = {
+      rgba16floatRenderable: true,
+      compute: true,
+      storageBuffer: true,
+      storageTexture: true,
+    } as never;
+    const catalog = createSceneDataCatalog({
+      featureIdentity: 'forgeax.motion-blur',
+      generation: 4,
+      planIdentity: 'forgeax.motion-blur:4',
+      rgba16floatRenderable: true,
+    });
+    const targets = [
+      {
+        name: 'motion-input',
+        kind: 'color' as const,
+        format: 'rgba16float' as const,
+        sampleCount: 1 as const,
+      },
+      {
+        name: 'motion-output',
+        kind: 'color' as const,
+        format: 'rgba16float' as const,
+        sampleCount: 1 as const,
+      },
+    ];
+    const planned = planMotionBlur(
+      DEFAULT_MOTION_BLUR_PARAMS,
+      {
+        caps: computeCaps,
+        frame: { frameNumber: 7, width: 1920, height: 1080 },
+        generation: 4,
+        targets,
+        sceneData: catalog,
+      },
+      { frameDeltaSeconds: 1 / 60, reset: false },
+    );
+    expect(planned.ok).toBe(true);
+    if (!planned.ok) return;
+    const frozen = freezeRenderFeaturePlan('forgeax.motion-blur', planned.value, targets);
+    expect(frozen.ok).toBe(true);
+    if (!frozen.ok) return;
+
+    const computeProgram = frozen.value.resources.find(
+      (resource) => resource.kind === 'compute-program',
+    );
+    const tileSummary = frozen.value.resources.find(
+      (resource) => resource.kind === 'buffer' && resource.name === 'motion-blur-tile-summary',
+    );
+    expect(computeProgram?.kind).toBe('compute-program');
+    expect(tileSummary).toMatchObject({
+      kind: 'buffer',
+      size: Math.ceil(1920 / 16) * Math.ceil(1080 / 16) * 32,
+      usage: ['storage'],
+    });
+    expect(frozen.value.passes.map((pass) => pass.name)).toEqual([
+      'motion-blur-tile-summary',
+      'motion-blur',
+    ]);
+    expect(frozen.value.passes).toHaveLength(2);
+    expect(frozen.value.passes[0]).toMatchObject({
+      kind: 'compute',
+      dispatches: [{ entryPoint: 'tile_summary', workgroups: [120, 68, 1] }],
+    });
+    expect(frozen.value.passes[1]).toMatchObject({
+      kind: 'compute',
+      dispatches: [{ entryPoint: 'reconstruct', workgroups: [240, 135, 1] }],
+    });
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('2.0 * (f32(index) + 0.5) / denominator - 1.0');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let sourcePixel = workgroupBase');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('halfFilteredColor');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('workgroupBarrier()');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('if (!inBounds) {');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('depthReject');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('sourceVelocitySegmentCovers');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('TILE_NEIGHBORHOOD_COUNT');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('tileIntersectsWorkgroupSupport');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('tileNeighborhoodOffset');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('const EDGE_FILL_FACTOR : f32 = 0.99;');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let acceptedColor');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let acceptedAlpha');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let emptyReceiver');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let sourceScale');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let sourceContribution');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let trailScale');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let outputAlpha');
+    expect(MOTION_BLUR_COMPUTE_WGSL).not.toContain('TILE_CANDIDATE_OFFSETS');
+    expect(MOTION_BLUR_COMPUTE_WGSL).not.toContain('atomic');
+    expect(MOTION_BLUR_COMPUTE_WGSL).not.toContain('textureSampleLevel');
+    if (computeProgram?.kind === 'compute-program') {
+      const entries = computeProgram.program.bindings?.[0]?.entries ?? [];
+      expect(entries.find((entry) => entry.binding === 2)?.buffer?.type).toBe('storage');
+      expect(entries.find((entry) => entry.binding === 3)?.storageTexture?.access).toBe(
+        'write-only',
+      );
+    }
+  });
+
+  it('compiles the compute lane WGSL before it reaches a backend', async () => {
+    const { compileShader } = await import(
+      /* @vite-ignore */
+      new URL('../../../../../shader-compiler/dist/index.mjs', import.meta.url).href
+    );
+    const compiled = await compileShader(MOTION_BLUR_COMPUTE_WGSL, {
+      id: 'forgeax::motion-blur-compute',
+    });
+    expect(compiled.ok, compiled.ok ? undefined : String(compiled.error)).toBe(true);
+  });
 });

package/src/features/motion-blur/__tests__/motion-blur-params.unit.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it } from 'vitest';
 import {
   DEFAULT_MOTION_BLUR_PARAMS,
+  effectiveMotionBlurSampleCount,
+  isMotionBlurIntervalValid,
+  motionBlurExposureScale,
+  motionBlurSampleDelta,
   motionBlurTemporalDemand,
   validateMotionBlurParams,
 } from '../motion-blur-params';
@@ -12,6 +16,7 @@ describe('Motion Blur parameter validation', () => {
       shutterAngle: 180,
       maxRadiusPixels: 32,
       sampleCount: 8,
+      targetFps: 60,
     });
   });
 
@@ -32,6 +37,9 @@ describe('Motion Blur parameter validation', () => {
     ['sampleCount', 3],
     ['sampleCount', 17],
     ['sampleCount', 8.5],
+    ['targetFps', -1],
+    ['targetFps', 240.5],
+    ['targetFps', 59.5],
   ] as const)('returns structured failure for %s=%s', (field, value) => {
     const result = validateMotionBlurParams({ [field]: value });
     expect(result.ok).toBe(false);
@@ -45,9 +53,56 @@ describe('Motion Blur parameter validation', () => {
 
   it('does no temporal work when omitted or shutter is zero', () => {
     expect(motionBlurTemporalDemand(undefined)).toBe(false);
-    expect(motionBlurTemporalDemand({ shutterAngle: 0, maxRadiusPixels: 32, sampleCount: 8 })).toBe(
-      false,
-    );
+    expect(
+      motionBlurTemporalDemand({
+        shutterAngle: 0,
+        maxRadiusPixels: 32,
+        sampleCount: 8,
+        targetFps: 60,
+      }),
+    ).toBe(false);
+    expect(
+      motionBlurTemporalDemand({
+        shutterAngle: 180,
+        maxRadiusPixels: 0,
+        sampleCount: 8,
+        targetFps: 60,
+      }),
+    ).toBe(false);
     expect(motionBlurTemporalDemand(DEFAULT_MOTION_BLUR_PARAMS)).toBe(true);
   });
+
+  it('rounds authored sample budgets down to the fixed shader tiers', () => {
+    expect(effectiveMotionBlurSampleCount(3)).toBe(0);
+    expect(effectiveMotionBlurSampleCount(4)).toBe(4);
+    expect(effectiveMotionBlurSampleCount(7)).toBe(4);
+    expect(effectiveMotionBlurSampleCount(8)).toBe(8);
+    expect(effectiveMotionBlurSampleCount(15)).toBe(8);
+    expect(effectiveMotionBlurSampleCount(16)).toBe(16);
+  });
+
+  it('rejects unstable intervals and scales displacement to the target rate', () => {
+    expect(isMotionBlurIntervalValid(1 / 60)).toBe(true);
+    expect(isMotionBlurIntervalValid(0)).toBe(false);
+    expect(isMotionBlurIntervalValid(0.101)).toBe(false);
+    expect(motionBlurExposureScale(1 / 60, 60)).toBeCloseTo(1);
+    expect(motionBlurExposureScale(1 / 120, 60)).toBeCloseTo(2);
+    expect(motionBlurExposureScale(1 / 60, 0)).toBe(1);
+    expect(motionBlurExposureScale(0, 60)).toBe(0);
+    expect(motionBlurExposureScale(1 / 60, 60.5)).toBe(0);
+    expect(motionBlurExposureScale(1 / 60, 241)).toBe(0);
+  });
+
+  it('keeps raw render hitches visible before ECS clamp policy', () => {
+    expect(motionBlurSampleDelta(1.2, 1, 0.1)).toBeCloseTo(0.2);
+    expect(motionBlurSampleDelta(1 / 30, 0, 0.1)).toBeCloseTo(1 / 30);
+    expect(isMotionBlurIntervalValid(motionBlurSampleDelta(1.2, 1, 0.1))).toBe(false);
+    expect(isMotionBlurIntervalValid(motionBlurSampleDelta(1 / 30, 0, 0.1))).toBe(true);
+    expect(motionBlurSampleDelta(undefined, undefined, 0.1)).toBe(0.1);
+  });
+
+  it('fails closed for an explicitly invalid host/replay sample', () => {
+    expect(Number.isNaN(motionBlurSampleDelta(Number.NaN, 1, 1 / 60))).toBe(true);
+    expect(Number.isNaN(motionBlurSampleDelta(1, Number.POSITIVE_INFINITY, 1 / 60))).toBe(true);
+  });
 });