@forgeax/engine-render 0.1.32 → 0.1.33

package/src/__tests__/bloom-exact-zero.unit.test.ts

@@ -5,11 +5,12 @@ import type { RhiDevice } from '@forgeax/engine-rhi';
 import { rhi } from '@forgeax/engine-rhi-null';
 import { ok } from '@forgeax/engine-types';
 import { beforeAll, describe, expect, it } from 'vitest';
+import { standardBloomAdmitted } from '../bloom-admission';
 import { prepareStandardLighting } from '../pipeline/standard-lighting/prepare';
 import { deriveStandardTopologyInput } from '../pipeline/standard-lighting/topology';
 import { selectStandardClusterTransport } from '../pipeline/standard-lighting/transport';
 import { standardPipeline } from '../pipeline/standard-pipeline';
-import { inspectStandardBloomGraph, STANDARD_BLOOM_TARGET_SPEC } from '../pipeline/standard-post';
+import { inspectStandardBloomGraph } from '../pipeline/standard-post';
 import { DEFAULT_STANDARD_PROFILE, STANDARD_PIPELINE_ID } from '../pipeline/standard-profile';
 import type { RenderPipelineFrame, RenderPipelineTopology } from '../render-pipeline';
 
@@ -23,7 +24,7 @@ beforeAll(async () => {
   device = result.value;
 });
 
-function topology(bloom: 'off' | 'on'): RenderPipelineTopology {
+function topology(bloom: 'off' | 'on', bloomIntensity = 1): RenderPipelineTopology {
   return {
     pipelineId: STANDARD_PIPELINE_ID,
     standardProfile: DEFAULT_STANDARD_PROFILE,
@@ -34,7 +35,12 @@ function topology(bloom: 'off' | 'on'): RenderPipelineTopology {
       storageFormat: 'bgra8unorm',
       viewFormat: 'bgra8unorm-srgb',
     },
-    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom },
+    camera: {
+      tonemap: 'aces-filmic',
+      antialias: 'fxaa',
+      bloom,
+      bloomIntensity,
+    },
     shadow: {
       directional: { mapSize: 64, cascadeCount: 1 },
       spotMapSize: 64,
@@ -80,7 +86,7 @@ function clusteredStandardLighting() {
   return lighting.value;
 }
 
-function inspect(bloom: 'off' | 'on') {
+function inspect(bloom: 'off' | 'on', bloomIntensity = 1) {
   const graph = new RenderGraphBuilder<RenderPipelineFrame>();
   const built = standardPipeline.build(
     {
@@ -89,7 +95,7 @@ function inspect(bloom: 'off' | 'on') {
       projectGpuDriven: () => ok(undefined),
       contributeFeatures: () => ok(undefined),
     },
-    topology(bloom),
+    topology(bloom, bloomIntensity),
   );
   if (!built.ok) throw built.error;
   const compiled = graph.compile({ device, surfaceSize: { width: 640, height: 360 } });
@@ -98,6 +104,15 @@ function inspect(bloom: 'off' | 'on') {
 }
 
 describe('Standard Bloom exact-zero topology', () => {
+  it.each([
+    ['off', 'aces-filmic', 1, false],
+    ['on', 'aces-filmic', 0, false],
+    ['on', 'none', 1, false],
+    ['on', 'aces-filmic', 1, true],
+  ] as const)('uses one effective admission for %s/%s/%s', (bloom, tonemap, intensity, expected) => {
+    expect(standardBloomAdmitted({ bloom, tonemap, bloomIntensity: intensity })).toBe(expected);
+  });
+
   it('Bloom off declares no Bloom targets or passes', () => {
     const info = inspect('off');
     const bloomPasses = info.passes.filter((pass) => pass.name.startsWith('bloom-'));
@@ -109,6 +124,10 @@ describe('Standard Bloom exact-zero topology', () => {
       targetCount: 0,
       targetBytes: 0,
       passCount: 0,
+      levelCount: 0,
+      levelDimensions: [],
+      downsamplePassCount: 0,
+      upsamplePassCount: 0,
     });
     expect({
       targetCount: bloomResources.length,
@@ -127,6 +146,15 @@ describe('Standard Bloom exact-zero topology', () => {
     });
   });
 
+  it('treats intensity=0 as exact-zero even when the Camera enum is on', () => {
+    const info = inspect('on', 0);
+    expect(info.passes.filter((pass) => pass.name.startsWith('bloom-'))).toHaveLength(0);
+    expect(info.resources.filter((resource) => resource.label.startsWith('bloom-'))).toHaveLength(
+      0,
+    );
+    expect(inspectStandardBloomGraph(info).status).toBe('empty');
+  });
+
   it('keeps Bloom declaration behind the camera gate in both lane owners', () => {
     const forwardSource = readFileSync(
       new URL('../pipeline/standard-forward-lane.ts', import.meta.url),
@@ -142,8 +170,8 @@ describe('Standard Bloom exact-zero topology', () => {
     );
     expect(forwardSource).toContain('addStandardPost');
     expect(clusteredSource).toContain('addStandardPost');
-    const gate = postSource.indexOf("topology.camera.bloom === 'on'");
-    const declaration = postSource.indexOf('STANDARD_BLOOM_TARGET_SPEC.composited');
+    const gate = postSource.indexOf('bloom: !clearOnly && standardBloomAdmitted(topology.camera)');
+    const declaration = postSource.indexOf('const bloomSpecs = standardBloomTargetSpecs(');
     expect(gate).toBeGreaterThanOrEqual(0);
     expect(declaration).toBeGreaterThan(gate);
   });
@@ -153,15 +181,27 @@ describe('Standard Bloom exact-zero topology', () => {
       const info = inspect('on');
       expect(inspectStandardBloomGraph(info)).toEqual({
         status: 'valid',
-        targetCount: 4,
-        targetBytes: (640 * 360 + 3 * 320 * 180) * 8,
-        passCount: 4,
+        targetCount: 10,
+        targetBytes: 3_069_440,
+        passCount: 10,
+        levelCount: 5,
+        levelDimensions: [
+          { width: 320, height: 180 },
+          { width: 160, height: 90 },
+          { width: 80, height: 45 },
+          { width: 40, height: 23 },
+          { width: 20, height: 12 },
+        ],
+        downsamplePassCount: 5,
+        upsamplePassCount: 4,
       });
-      expect(info.resources.find((resource) => resource.label === 'bloom-bright')).toMatchObject({
+      expect(
+        info.resources.find((resource) => resource.label === 'bloom-downsample-0'),
+      ).toMatchObject({
         descriptor: {
           kind: 'texture',
           format: 'rgba16float',
-          size: STANDARD_BLOOM_TARGET_SPEC.bright.size,
+          size: { width: 320, height: 180 },
           width: 320,
           height: 180,
           depthOrArrayLayers: 1,
@@ -171,7 +211,18 @@ describe('Standard Bloom exact-zero topology', () => {
       });
       expect(
         info.passes.map((pass) => pass.name).filter((name) => name.startsWith('bloom-')),
-      ).toEqual(['bloom-bright', 'bloom-blur-h', 'bloom-blur-v', 'bloom-composite']);
+      ).toEqual([
+        'bloom-downsample-0',
+        'bloom-downsample-1',
+        'bloom-downsample-2',
+        'bloom-downsample-3',
+        'bloom-downsample-4',
+        'bloom-upsample-3',
+        'bloom-upsample-2',
+        'bloom-upsample-1',
+        'bloom-upsample-0',
+        'bloom-composite',
+      ]);
     }
   });
 
@@ -180,7 +231,7 @@ describe('Standard Bloom exact-zero topology', () => {
     const drifted = {
       ...info,
       resources: info.resources.map((resource) =>
-        resource.label === STANDARD_BLOOM_TARGET_SPEC.bright.label
+        resource.label === 'bloom-downsample-0'
           ? {
               ...resource,
               descriptor:
@@ -196,6 +247,10 @@ describe('Standard Bloom exact-zero topology', () => {
       targetCount: 0,
       targetBytes: 0,
       passCount: 0,
+      levelCount: 0,
+      levelDimensions: [],
+      downsamplePassCount: 0,
+      upsamplePassCount: 0,
     });
   });
 
@@ -203,15 +258,17 @@ describe('Standard Bloom exact-zero topology', () => {
     const info = inspect('on');
     const drifted = {
       ...info,
-      resources: info.resources.filter(
-        (resource) => resource.label !== STANDARD_BLOOM_TARGET_SPEC.bright.label,
-      ),
+      resources: info.resources.filter((resource) => resource.label !== 'bloom-downsample-0'),
     };
     expect(inspectStandardBloomGraph(drifted)).toEqual({
       status: 'invalid',
       targetCount: 0,
       targetBytes: 0,
       passCount: 0,
+      levelCount: 0,
+      levelDimensions: [],
+      downsamplePassCount: 0,
+      upsamplePassCount: 0,
     });
   });
 
@@ -219,13 +276,50 @@ describe('Standard Bloom exact-zero topology', () => {
     const info = inspect('on');
     const drifted = {
       ...info,
-      passes: info.passes.filter((pass) => pass.name !== 'bloom-blur-h'),
+      passes: info.passes.filter((pass) => pass.name !== 'bloom-downsample-1'),
     };
     expect(inspectStandardBloomGraph(drifted)).toEqual({
       status: 'invalid',
       targetCount: 0,
       targetBytes: 0,
       passCount: 0,
+      levelCount: 0,
+      levelDimensions: [],
+      downsamplePassCount: 0,
+      upsamplePassCount: 0,
+    });
+  });
+
+  it('rejects forged odd-scale extents instead of reporting inferred sizes or cost', () => {
+    const info = inspect('on');
+    const forgedLabels = new Set(['bloom-downsample-0', 'bloom-downsample-1', 'bloom-upsample-0']);
+    const forged = {
+      ...info,
+      resources: info.resources.map((resource) =>
+        forgedLabels.has(resource.label) && resource.descriptor.kind === 'texture'
+          ? {
+              ...resource,
+              descriptor: {
+                ...resource.descriptor,
+                size: { width: 4, height: 4 },
+                width: 4,
+                height: 4,
+              },
+              extent: { width: 4, height: 4, depthOrArrayLayers: 1 },
+              byteSize: 128,
+            }
+          : resource,
+      ),
+    };
+    expect(inspectStandardBloomGraph(forged)).toEqual({
+      status: 'invalid',
+      targetCount: 0,
+      targetBytes: 0,
+      passCount: 0,
+      levelCount: 0,
+      levelDimensions: [],
+      downsamplePassCount: 0,
+      upsamplePassCount: 0,
     });
   });
 });

package/src/__tests__/bloom-lifecycle.integration.test.ts

@@ -33,7 +33,12 @@ function build(bloom: 'off' | 'on') {
       storageFormat: 'bgra8unorm',
       viewFormat: 'bgra8unorm-srgb',
     },
-    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom },
+    camera: {
+      tonemap: 'aces-filmic',
+      antialias: 'fxaa',
+      bloom,
+      bloomIntensity: 1,
+    },
     shadow: {
       directional: { mapSize: 64, cascadeCount: 1 },
       spotMapSize: 64,
@@ -103,7 +108,7 @@ describe('Standard Bloom lifecycle contract', () => {
     const on = bloomSummary(build('on'));
     const off = bloomSummary(build('off'));
     const recovered = bloomSummary(build('on'));
-    expect(on.passes).toHaveLength(4);
+    expect(on.passes).toHaveLength(10);
     expect(on.resources.length).toBeGreaterThan(0);
     expect(off).toEqual({ passes: [], resources: [] });
     expect(recovered).toEqual(on);
@@ -113,7 +118,15 @@ describe('Standard Bloom lifecycle contract', () => {
     const names = build('on').passes.map((pass) => pass.name);
     const order = [
       'forward',
-      'bloom-bright',
+      'bloom-downsample-0',
+      'bloom-downsample-1',
+      'bloom-downsample-2',
+      'bloom-downsample-3',
+      'bloom-downsample-4',
+      'bloom-upsample-3',
+      'bloom-upsample-2',
+      'bloom-upsample-1',
+      'bloom-upsample-0',
       'bloom-composite',
       'output-transform',
       'fxaa',
@@ -132,7 +145,7 @@ describe('Standard Bloom lifecycle contract', () => {
     const transaction = new LifecycleTransaction(bloom);
     transaction.add({
       kind: 'texture',
-      create: () => ({ label: 'bloom-bright' }),
+      create: () => ({ label: 'bloom-downsample-0' }),
       cleanup: () => undefined,
     });
     const committed = await transaction.commit();

package/src/__tests__/dynamic-resolution-plugin.integration.test.ts

@@ -69,13 +69,33 @@ describe('DynamicResolution render component registration', () => {
       shutterAngle: 120,
       maxRadiusPixels: 12,
       sampleCount: 6,
+      targetFps: 60,
     });
     expect(extractFrames([world], 0).cameras[0]?.motionBlur).toEqual({
       shutterAngle: 120,
       maxRadiusPixels: 12,
       sampleCount: 6,
+      targetFps: 60,
     });
 
     await context.fiber.dispose();
   });
+
+  it('routes invalid MotionBlur data through the structured extraction error', async () => {
+    const world = new World();
+    const context = await createWorldContext(world, [renderComponentsPlugin(), scenePlugin()]);
+    world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: Camera, data: { antialias: ANTIALIAS_TAA } },
+        { component: MotionBlur, data: { targetFps: 59.5 } },
+      )
+      .unwrap();
+    world.update(1 / 60).unwrap();
+
+    expect(() => extractCameraSnapshots(world)).toThrowError(
+      expect.objectContaining({ code: 'motion-blur-invalid-params' }),
+    );
+    await context.fiber.dispose();
+  });
 });

package/src/__tests__/environment-fog-lanes.integration.test.ts

@@ -20,6 +20,8 @@ const frame = selectEnvironment({
         mieCoefficient: 0.005,
         mieDirectionalG: 0.8,
         sunAngularRadius: 0.004675,
+        circumsolarStrength: 1,
+        circumsolarWidth: 1,
       },
     },
   ],
@@ -48,6 +50,8 @@ describe('Environment and Fog lane graph contract', () => {
           mieCoefficient: 0.006,
           mieDirectionalG: 0.7,
           sunAngularRadius: 0.01,
+          circumsolarStrength: 1.4,
+          circumsolarWidth: 1.6,
         },
       })
       .unwrap();
@@ -70,6 +74,8 @@ describe('Environment and Fog lane graph contract', () => {
     expect(extracted.environment.source.atmosphere?.mieCoefficient).toBeCloseTo(0.006);
     expect(extracted.environment.source.atmosphere?.mieDirectionalG).toBeCloseTo(0.7);
     expect(extracted.environment.source.atmosphere?.sunAngularRadius).toBeCloseTo(0.01);
+    expect(extracted.environment.source.atmosphere?.circumsolarStrength).toBeCloseTo(1.4);
+    expect(extracted.environment.source.atmosphere?.circumsolarWidth).toBeCloseTo(1.6);
     const signature = JSON.parse(extracted.environment.signature) as {
       environments: [{ atmosphere: Record<string, number> }];
       suns: [{ direction: [number, number, number] }];
@@ -79,6 +85,8 @@ describe('Environment and Fog lane graph contract', () => {
     expect(signature.environments[0].atmosphere.mieCoefficient).toBeCloseTo(0.006);
     expect(signature.environments[0].atmosphere.mieDirectionalG).toBeCloseTo(0.7);
     expect(signature.environments[0].atmosphere.sunAngularRadius).toBeCloseTo(0.01);
+    expect(signature.environments[0].atmosphere.circumsolarStrength).toBeCloseTo(1.4);
+    expect(signature.environments[0].atmosphere.circumsolarWidth).toBeCloseTo(1.6);
     expect(signature.suns[0].direction).toEqual([0, 1, 0]);
   });
 
@@ -162,6 +170,8 @@ describe('Environment and Fog lane graph contract', () => {
           mieCoefficient: 0.005,
           mieDirectionalG: 0.8,
           sunAngularRadius: 0.004675,
+          circumsolarStrength: 1,
+          circumsolarWidth: 1,
         },
       })
       .unwrap();
@@ -190,6 +200,8 @@ describe('Environment and Fog lane graph contract', () => {
         mieCoefficient: 0.005,
         mieDirectionalG: 0.8,
         sunAngularRadius: 0.004675,
+        circumsolarStrength: 1,
+        circumsolarWidth: 1,
       })
       .unwrap();
     const invalid = extractFrames([world], 0);
@@ -203,6 +215,8 @@ describe('Environment and Fog lane graph contract', () => {
         mieCoefficient: 0.006,
         mieDirectionalG: 0.7,
         sunAngularRadius: 0.01,
+        circumsolarStrength: 1,
+        circumsolarWidth: 1,
       })
       .unwrap();
     const corrected = extractFrames([world], 0);

package/src/__tests__/environment-selection.unit.test.ts

@@ -7,6 +7,7 @@ import type {
   EnvironmentCandidate,
   FogCandidate,
 } from '../extract/environment';
+import { SunCardinalityError } from '../index';
 
 const atmosphereParameters: AtmosphereParameters = {
   turbidity: 2,
@@ -14,6 +15,8 @@ const atmosphereParameters: AtmosphereParameters = {
   mieCoefficient: 0.005,
   mieDirectionalG: 0.8,
   sunAngularRadius: 0.004675,
+  circumsolarStrength: 1,
+  circumsolarWidth: 1,
 };
 
 const image = (entityKey: number, sourceKey: string): EnvironmentCandidate => ({
@@ -97,6 +100,7 @@ describe('Environment and Fog selection (M2)', () => {
     expect(result.error.expected).toContain('sun');
     expect(result.error.hint).toContain('sun');
     expect(result.error.detail).toMatchObject({ field, value });
+    expect(result.error).toBeInstanceOf(SunCardinalityError);
   });
 
   it('rejects invalid Fog parameters at the field owner', () => {
@@ -114,6 +118,8 @@ describe('Environment and Fog selection (M2)', () => {
     ['mieCoefficient', { mieCoefficient: -0.001 }],
     ['mieDirectionalG', { mieDirectionalG: 1.1 }],
     ['sunAngularRadius', { sunAngularRadius: Number.POSITIVE_INFINITY }],
+    ['circumsolarStrength', { circumsolarStrength: -0.001 }],
+    ['circumsolarWidth', { circumsolarWidth: 0.1 }],
   ] as const)('rejects invalid Atmosphere.%s with field-owned detail', (field, override) => {
     const result = selection(
       [
@@ -141,6 +147,8 @@ describe('Environment and Fog selection (M2)', () => {
     ['mieCoefficient', 0, 100],
     ['mieDirectionalG', 0, 0.999],
     ['sunAngularRadius', 0, 1],
+    ['circumsolarStrength', 0, 4],
+    ['circumsolarWidth', 0.25, 4],
   ] as const)('accepts the documented %s boundaries', (field, minimum, maximum) => {
     for (const value of [minimum, maximum]) {
       const result = selection(
@@ -165,6 +173,8 @@ describe('Environment and Fog selection (M2)', () => {
     ['mieCoefficient', [-Number.MIN_VALUE, Number.POSITIVE_INFINITY]],
     ['mieDirectionalG', [-Number.MIN_VALUE, 1]],
     ['sunAngularRadius', [-Number.MIN_VALUE, Number.POSITIVE_INFINITY]],
+    ['circumsolarStrength', [-Number.MIN_VALUE, 4.001]],
+    ['circumsolarWidth', [0.249, 4.001]],
   ] as const)('rejects %s values outside the shared shader domain', (field, values) => {
     for (const value of values) {
       const result = selection(
@@ -207,6 +217,8 @@ describe('Environment and Fog selection (M2)', () => {
     expect(baseline.value.source).toMatchObject({ atmosphere: atmosphereParameters });
     expect(baseline.value.signature).not.toBe(changed.value.signature);
     expect(baseline.value.signature).toContain('sunAngularRadius');
+    expect(baseline.value.signature).toContain('circumsolarStrength');
+    expect(baseline.value.signature).toContain('circumsolarWidth');
   });
 
   it('keeps Fog orthogonal and produces identical direct/clustered frame facts', () => {