@forgeax/engine-runtime 0.1.21 → 0.1.24

package/src/__tests__/light-gpu-byte-neutral.unit.test.ts

@@ -7,8 +7,8 @@
 // lock the four light GPU pack paths' byte output so the collapse is proven
 // byte-neutral end to end:
 //   1. View UBO (DirectionalLight direction/color lanes)   -> writeViewUbo
-//   2. PointLightBuffer (color lanes)                       -> packPointLight
-//   3. SpotLightBuffer (direction + color lanes)            -> packSpotLight
+//   2. PointLightBuffer (color lanes)                       -> packDirectLightSlot
+//   3. SpotLightBuffer (direction + color lanes)            -> packDirectLightSlot
 //   4. Skylight uniform/ambient (color destructure)         -> SkylightSnapshot
 // (Camera clear pass is M3, not here.)
 
@@ -16,7 +16,7 @@ import { vec3 } from '@forgeax/engine-math';
 import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
 import { ok } from '@forgeax/engine-rhi';
 import { describe, expect, it } from 'vitest';
-import { packPointLight, packSpotLight } from '../../../render/src/light-buffer-layout';
+import { packDirectLightSlot } from '../../../render/src/light-buffer-layout';
 import { writeViewUbo } from '../../../render/src/record/view-ubo';
 import type { CameraSnapshot } from '../../../render/src/render-contract';
 import type {
@@ -83,7 +83,7 @@ function captureViewUbo(light: DirectionalLightSnapshot): { payload: Float32Arra
 }
 
 describe('w7 -- light GPU pack byte-neutral (AC-11)', () => {
-  it('View UBO packs DirectionalLight direction*intensity / color into lanes 16..18 / 20..22', () => {
+  it('View UBO packs raw DirectionalLight direction / color into lanes 16..18 / 20..22', () => {
     const light: DirectionalLightSnapshot = {
       kind: 'directional',
       direction: vec3.create(-0.5, -1, -0.3),
@@ -93,17 +93,18 @@ describe('w7 -- light GPU pack byte-neutral (AC-11)', () => {
       intensity: 2,
     };
     const { payload } = captureViewUbo(light);
-    // lightDir lanes carry direction * intensity (view-ubo.ts:66-68).
-    expect(payload[16]).toBeCloseTo(-0.5 * 2, 5);
-    expect(payload[17]).toBeCloseTo(-1 * 2, 5);
-    expect(payload[18]).toBeCloseTo(-0.3 * 2, 5);
+    // lightDir lanes carry the raw outgoing direction; the shader applies
+    // the light's radiance from the already premultiplied color lanes.
+    expect(payload[16]).toBeCloseTo(-0.5, 5);
+    expect(payload[17]).toBeCloseTo(-1, 5);
+    expect(payload[18]).toBeCloseTo(-0.3, 5);
     // lightColor lanes carry the (already pre-multiplied) color verbatim.
     expect(payload[20]).toBeCloseTo(0.9, 5);
     expect(payload[21]).toBeCloseTo(0.8, 5);
     expect(payload[22]).toBeCloseTo(0.7, 5);
   });
 
-  it('packPointLight writes color into slots 4..6 byte-for-byte (32 B)', () => {
+  it('packDirectLightSlot writes Point color into slots 4..6 byte-for-byte (80 B)', () => {
     const snap: PointLightSnapshot = {
       kind: 'point',
       position: vec3.create(1.5, -2.25, 0.125),
@@ -111,14 +112,14 @@ describe('w7 -- light GPU pack byte-neutral (AC-11)', () => {
       intensity: 2,
       invRangeSquared: 0.04,
     };
-    const out = packPointLight(snap);
-    expect(out.byteLength).toBe(32);
+    const out = packDirectLightSlot(snap);
+    expect(out.byteLength).toBe(80);
     expect(out[4]).toBeCloseTo(0.4, 6);
     expect(out[5]).toBeCloseTo(0.5, 6);
     expect(out[6]).toBeCloseTo(0.6, 6);
   });
 
-  it('packSpotLight writes color slots 4..6 + direction slots 8..10 byte-for-byte (80 B)', () => {
+  it('packDirectLightSlot writes Spot color slots 4..6 + direction slots 8..10 byte-for-byte (80 B)', () => {
     const snap: SpotLightSnapshot = {
       kind: 'spot',
       position: vec3.create(0, 5, 0),
@@ -135,9 +136,7 @@ describe('w7 -- light GPU pack byte-neutral (AC-11)', () => {
       farPlane: 50,
       shadowAtlasTile: -1,
     };
-    const out = packSpotLight(snap);
-    // SpotLight carries projector receiver controls and the shadow intensity
-    // tail in the current std430 payload.
+    const out = packDirectLightSlot(snap);
     expect(out.byteLength).toBe(80);
     expect(out[4]).toBeCloseTo(0.3, 6);
     expect(out[5]).toBeCloseTo(0.4, 6);

package/src/__tests__/light-snapshot.test-d.ts

@@ -23,11 +23,16 @@
 import { expectTypeOf, test } from 'vitest';
 import type { DirectionalShadowQuality } from '../../../render/src/components/directional-shadow-filter';
 import type { LightValidationError } from '../../../render/src/components/light-helpers';
+import type {
+  DirectLightSlotKind,
+  DirectLightSnapshot,
+} from '../../../render/src/light-buffer-layout';
 import type {
   DirectionalLightSnapshot,
   ExtractedLights,
   LightSnapshot,
   PointLightSnapshot,
+  RectAreaDirectLightSnapshot,
   SpotLightSnapshot,
 } from '../../../render/src/render-system-extract';
 
@@ -46,6 +51,8 @@ function consumeSnapshot(s: LightSnapshot): number {
       return s.invRangeSquared;
     case 'spot':
       return s.cosInner + s.cosOuter;
+    case 'rect-area':
+      return s.halfWidth + s.halfHeight;
     default:
       return assertNever(s);
   }
@@ -53,7 +60,7 @@ function consumeSnapshot(s: LightSnapshot): number {
 
 test('LightSnapshot is a discriminated union on kind', () => {
   expectTypeOf<LightSnapshot>().toEqualTypeOf<
-    DirectionalLightSnapshot | PointLightSnapshot | SpotLightSnapshot
+    DirectionalLightSnapshot | PointLightSnapshot | SpotLightSnapshot | RectAreaDirectLightSnapshot
   >();
   // Smoke that the consumer compiles (run-time noop; compile-time exhaustive).
   void consumeSnapshot;
@@ -83,6 +90,25 @@ test('ExtractedLights three-bucket shape', () => {
   expectTypeOf<ExtractedLights['directionalCount']>().toEqualTypeOf<number>();
   expectTypeOf<ExtractedLights['point']>().toEqualTypeOf<readonly PointLightSnapshot[]>();
   expectTypeOf<ExtractedLights['spot']>().toEqualTypeOf<readonly SpotLightSnapshot[]>();
+  expectTypeOf<ExtractedLights['rect']>().toEqualTypeOf<readonly RectAreaDirectLightSnapshot[]>();
+});
+
+function consumeDirectLight(snapshot: DirectLightSnapshot): number {
+  switch (snapshot.kind) {
+    case 'point':
+      return snapshot.invRangeSquared;
+    case 'spot':
+      return snapshot.cosInner + snapshot.cosOuter;
+    case 'rect-area':
+      return snapshot.halfWidth + snapshot.halfHeight;
+    default:
+      return assertNever(snapshot);
+  }
+}
+
+test('DirectLightSlot kind is closed and includes only finite direct lights', () => {
+  expectTypeOf<DirectLightSlotKind>().toEqualTypeOf<'point' | 'spot' | 'rect-area'>();
+  void consumeDirectLight;
   expectTypeOf<ExtractedLights['directionalShadowQuality']>().toEqualTypeOf<
     DirectionalShadowQuality | undefined
   >();

package/src/__tests__/lights-preservation.fixup.test.ts

@@ -9,11 +9,7 @@ import {
   validatePointLightShadowData,
   validateSpotLightData,
 } from '../../../render/src/components/light-helpers';
-import {
-  packLightSlot,
-  packPointLight,
-  packSpotLight,
-} from '../../../render/src/light-buffer-layout';
+import { packDirectLightSlot } from '../../../render/src/light-buffer-layout';
 import { buildPbrViewBglEntries } from '../../../render/src/pbr-pipeline';
 import type {
   PointLightSnapshot,
@@ -87,32 +83,34 @@ describe('Point/Spot and shared-light regression guard', () => {
     expect(degToCos(60)).toBeCloseTo(0.5, 8);
   });
 
-  it('keeps Point/Spot packing and the shared LightSlot discriminant intact', () => {
+  it('keeps Point/Spot packing in the shared DirectLightSlot owner', () => {
     const point = pointSnapshot();
     const spot = spotSnapshot();
-    const pointPacked = packPointLight(point);
-    const spotPacked = packSpotLight(spot);
-    const pointSlot = packLightSlot(point, { shadowAtlasLayer: 2, near: 0.1, far: 20 });
-    const spotSlot = packLightSlot(spot);
+    const pointSlot = packDirectLightSlot({ ...point, shadowAtlasLayer: 2 });
+    const spotSlot = packDirectLightSlot(spot);
 
-    expect(pointPacked.byteLength).toBe(32);
-    expect(spotPacked.byteLength).toBe(80);
-    expect(new Uint32Array(pointSlot.buffer)[12]).toBe(0);
-    expect(new Int32Array(pointSlot.buffer)[13]).toBe(2);
-    expect(new Uint32Array(spotSlot.buffer)[12]).toBe(1);
-    expect(new Int32Array(spotSlot.buffer)[13]).toBe(-1);
+    expect(pointSlot.byteLength).toBe(80);
+    expect(spotSlot.byteLength).toBe(80);
+    expect(new Uint32Array(pointSlot.buffer)[16]).toBe(0);
+    expect(new Uint32Array(pointSlot.buffer)[17]).toBe(2);
+    expect(new Uint32Array(spotSlot.buffer)[16]).toBe(1);
+    expect(new Uint32Array(spotSlot.buffer)[17]).toBe(0xffffffff);
   });
 
-  it('keeps shared PBR view bindings for both storage and uniform light routes', () => {
+  it('keeps the PBR view layout independent from cluster light storage capability', () => {
     const storageBindings = buildPbrViewBglEntries({ storageBuffer: true });
     const uniformBindings = buildPbrViewBglEntries({ storageBuffer: false });
     expect(storageBindings.map((entry) => entry.binding)).toEqual(
       uniformBindings.map((entry) => entry.binding),
     );
-    expect(storageBindings[1]?.buffer?.type).toBe('read-only-storage');
-    expect(storageBindings[2]?.buffer?.type).toBe('read-only-storage');
-    expect(uniformBindings[1]?.buffer?.type).toBe('uniform');
-    expect(uniformBindings[2]?.buffer?.type).toBe('uniform');
+    // Local lights are consumed through the cluster payload in group(2). The
+    // shared view group therefore has no legacy direct-light storage/uniform
+    // entries at bindings 1/2, and its shape cannot drift with the capability
+    // route selected for the cluster buffers.
+    expect(storageBindings.find((entry) => entry.binding === 1)).toBeUndefined();
+    expect(storageBindings.find((entry) => entry.binding === 2)).toBeUndefined();
+    expect(uniformBindings.find((entry) => entry.binding === 1)).toBeUndefined();
+    expect(uniformBindings.find((entry) => entry.binding === 2)).toBeUndefined();
   });
 
   it('keeps Point/Spot pcfKernelSize validation independent of Directional quality', () => {