@forgeax/engine-render 0.1.2

package/src/extract/__tests__/directional-csm-domain.unit.test.ts

@@ -0,0 +1,391 @@
+import { World } from '@forgeax/engine-ecs';
+import { mat4, vec3 } from '@forgeax/engine-math';
+import {
+  Camera,
+  type CsmCameraData,
+  computeDirectionalCsm,
+  DirectionalLight,
+  directionalCascadeAtlasSize,
+  extractFrame,
+  prepareExtractContext,
+} from '@forgeax/engine-render/internal';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+
+const LIGHT_DIRECTION_VALUES: readonly [number, number, number] = [0.37, -0.86, 0.21];
+const LIGHT_DIRECTION = vec3.create(...LIGHT_DIRECTION_VALUES);
+
+const CONFIG = {
+  cascadeCount: 2,
+  splitLambda: 0.5,
+  cascadeBlend: 0.25,
+  mapSize: 1024,
+  shadowDistance: 50,
+};
+
+function cameraWorld(yaw = 0, x = 0): Float32Array {
+  const world = mat4.fromRotation(mat4.create(), [0, 1, 0], yaw);
+  world[12] = x;
+  return world;
+}
+
+function cameraData(yaw = 0, x = 0): CsmCameraData {
+  return {
+    world: cameraWorld(yaw, x),
+    fov: Math.PI / 3,
+    aspect: 1,
+    near: 0.1,
+    far: 100,
+    projection: 'perspective',
+    orthoLeft: -1,
+    orthoRight: 1,
+    orthoBottom: -1,
+    orthoTop: 1,
+  };
+}
+
+function halfExtent(matrix: Float32Array): number {
+  const scaleX = Math.hypot(matrix[0] ?? 0, matrix[1] ?? 0, matrix[2] ?? 0);
+  return 1 / scaleX;
+}
+
+function extractWithShadowFields(pcfKernelSize: number, mapSize: number): Float32Array {
+  const world = new World();
+  world.spawn({
+    component: DirectionalLight,
+    data: {
+      direction: LIGHT_DIRECTION,
+      cascadeCount: 1,
+      shadowDistance: 50,
+      pcfKernelSize,
+      mapSize,
+    },
+  });
+  world.spawn(
+    { component: Transform, data: {} },
+    { component: Camera, data: { fov: Math.PI / 3, aspect: 1, near: 0.1, far: 100 } },
+  );
+  const frame = extractFrame(world, prepareExtractContext(world));
+  const matrix = frame.lights.lightViewProj?.[0];
+  if (!(matrix instanceof Float32Array)) throw new Error('directional CSM matrix is unavailable');
+  return matrix;
+}
+
+describe('directional CSM receiver domain', () => {
+  it('keeps atlas dimensions aligned with the cascade tile topology', () => {
+    expect(directionalCascadeAtlasSize(1, 1024)).toEqual({ width: 1024, height: 1024 });
+    expect(directionalCascadeAtlasSize(2, 1024)).toEqual({ width: 2048, height: 1024 });
+    expect(directionalCascadeAtlasSize(3, 1024)).toEqual({ width: 2048, height: 2048 });
+  });
+
+  it('does not poison the frame when a perspective camera has no aspect', () => {
+    expect(
+      computeDirectionalCsm(LIGHT_DIRECTION, CONFIG, { ...cameraData(), aspect: 0 }),
+    ).toBeNull();
+  });
+
+  it('fits the next cascade across the previous cascade blend receiver band', () => {
+    const result = computeDirectionalCsm(LIGHT_DIRECTION, CONFIG, cameraData());
+    expect(result).not.toBeNull();
+    if (result === null) return;
+    const split = result.splitPlanes[0] ?? 0;
+    const observation = result as unknown as {
+      readonly cascades?: readonly [
+        unknown,
+        { readonly receiverViewDepth: readonly [number, number] },
+      ];
+    };
+    expect(observation.cascades).toBeDefined();
+    if (observation.cascades === undefined) return;
+    const nextReceiver = observation.cascades[1];
+    expect(nextReceiver).toBeDefined();
+    if (nextReceiver === undefined) return;
+    expect(nextReceiver.receiverViewDepth[0]).toBeLessThanOrEqual(
+      split * (1 - CONFIG.cascadeBlend),
+    );
+  });
+
+  it('keeps receiver extent invariant when the camera rotates', () => {
+    const baseline = computeDirectionalCsm(LIGHT_DIRECTION, CONFIG, cameraData(0));
+    const rotated = computeDirectionalCsm(LIGHT_DIRECTION, CONFIG, cameraData(0.43));
+    expect(baseline).not.toBeNull();
+    expect(rotated).not.toBeNull();
+    if (baseline === null || rotated === null) return;
+    const baselineExtent = baseline.cascades[0]?.stableExtent;
+    const rotatedExtent = rotated.cascades[0]?.stableExtent;
+    expect(baselineExtent).toBeDefined();
+    expect(rotatedExtent).toBeDefined();
+    if (baselineExtent === undefined || rotatedExtent === undefined) return;
+
+    // stableExtent is the producer's lateral-fit SSOT. Matrix column 0 also
+    // reflects the independently fitted depth range, so it is not a valid
+    // measurement of rotation invariance after Z fit becomes cascade-local.
+    expect(rotatedExtent).toBeCloseTo(baselineExtent, 5);
+  });
+
+  it('snaps a sub-texel light-space camera move to the same matrix', () => {
+    const baseline = computeDirectionalCsm(LIGHT_DIRECTION, CONFIG, cameraData(0, 0));
+    const moved = computeDirectionalCsm(LIGHT_DIRECTION, CONFIG, cameraData(0, 0.001));
+    expect(baseline).not.toBeNull();
+    expect(moved).not.toBeNull();
+    if (baseline === null || moved === null) return;
+    const baselineMatrix = baseline.lightViewProj[0];
+    const movedMatrix = moved.lightViewProj[0];
+    expect(baselineMatrix).toBeDefined();
+    expect(movedMatrix).toBeDefined();
+    if (baselineMatrix === undefined || movedMatrix === undefined) return;
+
+    expect(Array.from(movedMatrix)).toEqual(Array.from(baselineMatrix));
+  });
+
+  it('keeps the complete XYZ fit stable with a real caster candidate domain', () => {
+    const candidates = [
+      {
+        renderableIndex: 7,
+        worldId: 3,
+        entityKey: 11,
+        worldAabb: new Float32Array([-4, -1, -12, 4, 4, -8]),
+        bounded: true,
+        shadowCaster: true,
+      },
+    ];
+    const baseline = computeDirectionalCsm(LIGHT_DIRECTION, CONFIG, cameraData(0, 0), candidates);
+    const moved = computeDirectionalCsm(LIGHT_DIRECTION, CONFIG, cameraData(0, 0.001), candidates);
+    expect(baseline).not.toBeNull();
+    expect(moved).not.toBeNull();
+    if (baseline === null || moved === null) return;
+    const baselineMatrix = baseline.lightViewProj[0];
+    const movedMatrix = moved.lightViewProj[0];
+    expect(baselineMatrix).toBeDefined();
+    expect(movedMatrix).toBeDefined();
+    if (baselineMatrix === undefined || movedMatrix === undefined) return;
+
+    expect(baseline.cascades[0]?.casterRenderableIndices).toContain(7);
+    expect(moved.cascades[0]?.casterRenderableIndices).toContain(7);
+    expect(Array.from(movedMatrix)).toEqual(Array.from(baselineMatrix));
+  });
+
+  it('keeps bounded caster depth local to the cascade instead of the full shadow range', () => {
+    const result = computeDirectionalCsm(
+      LIGHT_DIRECTION,
+      { ...CONFIG, collectCandidateDecisions: true },
+      cameraData(),
+      [
+        {
+          renderableIndex: 7,
+          worldId: 3,
+          entityKey: 11,
+          worldAabb: new Float32Array([-0.5, -0.5, -0.5, 0.5, 0.5, 0.5]),
+          bounded: true,
+          shadowCaster: true,
+        },
+      ],
+    );
+    expect(result).not.toBeNull();
+    if (result === null) return;
+    const cascade = result.cascades[0];
+    expect(cascade).toBeDefined();
+    if (cascade === undefined) return;
+
+    const clipMinZ = cascade.clipLightBounds[4] ?? Infinity;
+    const clipMaxZ = cascade.clipLightBounds[5] ?? -Infinity;
+    const receiverMinZ = cascade.receiverLightBounds[4] ?? -Infinity;
+    const receiverMaxZ = cascade.receiverLightBounds[5] ?? Infinity;
+    expect(clipMinZ).toBeLessThanOrEqual(receiverMinZ);
+    expect(clipMaxZ).toBeGreaterThanOrEqual(receiverMaxZ);
+    // A full-shadow-range sphere would make cascade 0 span most of the 50u
+    // shadow distance, destroying depth precision for a nearby caster.
+    expect(clipMaxZ - clipMinZ).toBeLessThan(CONFIG.shadowDistance);
+  });
+
+  it('does not let a selected caster away-light tail expand the depth fit', () => {
+    const baseCaster = {
+      renderableIndex: 7,
+      worldId: 3,
+      entityKey: 11,
+      worldAabb: new Float32Array([-0.5, -0.5, -0.5, 0.5, 0.5, 0.5]),
+      bounded: true,
+      shadowCaster: true,
+    };
+    const tailCaster = {
+      ...baseCaster,
+      worldAabb: new Float32Array([-0.5, -10, -0.5, 0.5, 0.5, 0.5]),
+    };
+    const candidateConfig = { ...CONFIG, collectCandidateDecisions: true };
+    const base = computeDirectionalCsm(LIGHT_DIRECTION, candidateConfig, cameraData(), [
+      baseCaster,
+    ]);
+    const withTail = computeDirectionalCsm(LIGHT_DIRECTION, candidateConfig, cameraData(), [
+      tailCaster,
+    ]);
+    expect(base).not.toBeNull();
+    expect(withTail).not.toBeNull();
+    if (base === null || withTail === null) return;
+    const baseCascade = base.cascades[0];
+    const tailCascade = withTail.cascades[0];
+    expect(baseCascade).toBeDefined();
+    expect(tailCascade).toBeDefined();
+    if (baseCascade === undefined || tailCascade === undefined) return;
+
+    const baseBounds = baseCascade.candidateDecisions?.[0]?.lightSpaceBounds;
+    const tailBounds = tailCascade.candidateDecisions?.[0]?.lightSpaceBounds;
+    expect(baseCascade.casterRenderableIndices).toContain(7);
+    expect(tailCascade.casterRenderableIndices).toContain(7);
+    expect(baseCascade.candidateDecisions?.[0]?.selected).toBe(true);
+    expect(tailCascade.candidateDecisions?.[0]?.selected).toBe(true);
+    expect(baseBounds).toBeDefined();
+    expect(tailBounds).toBeDefined();
+    if (baseBounds === undefined || tailBounds === undefined) return;
+    expect(tailBounds[4]).toBeLessThan(baseBounds[4] ?? Infinity);
+    expect(tailBounds[5]).toBeCloseTo(baseBounds[5] ?? -Infinity, 5);
+    expect(tailCascade.clipLightBounds[4]).toBe(baseCascade.clipLightBounds[4]);
+    expect(Array.from(tailCascade.lightViewProj)).toEqual(Array.from(baseCascade.lightViewProj));
+  });
+
+  it('keeps both whole-frustum depth sides for empty and unbounded candidate domains', () => {
+    const cases = [
+      [],
+      [
+        {
+          renderableIndex: 9,
+          worldId: 4,
+          entityKey: 12,
+          worldAabb: null,
+          bounded: false,
+          shadowCaster: true,
+        },
+      ],
+    ] as const;
+    for (const candidates of cases) {
+      const result = computeDirectionalCsm(
+        LIGHT_DIRECTION,
+        { ...CONFIG, collectCandidateDecisions: true },
+        cameraData(),
+        candidates,
+      );
+      expect(result).not.toBeNull();
+      if (result === null) continue;
+      const cascade = result.cascades[0];
+      expect(cascade).toBeDefined();
+      if (cascade === undefined) continue;
+
+      const clipMinZ = cascade.clipLightBounds[4] ?? Infinity;
+      const clipMaxZ = cascade.clipLightBounds[5] ?? -Infinity;
+      const receiverMinZ = cascade.receiverLightBounds[4] ?? -Infinity;
+      const receiverMaxZ = cascade.receiverLightBounds[5] ?? Infinity;
+      expect(clipMinZ).toBeLessThan(receiverMinZ);
+      expect(clipMinZ).toBeLessThanOrEqual(cascade.lightSpaceMinZFull);
+      expect(clipMaxZ).toBeGreaterThanOrEqual(receiverMaxZ);
+      expect(clipMaxZ).toBeGreaterThanOrEqual(cascade.lightSpaceMaxZFull);
+    }
+  });
+
+  it('extends the toward-light clip side for a selected bounded caster', () => {
+    const result = computeDirectionalCsm(
+      LIGHT_DIRECTION,
+      { ...CONFIG, collectCandidateDecisions: true },
+      cameraData(),
+      [
+        {
+          renderableIndex: 10,
+          worldId: 5,
+          entityKey: 13,
+          worldAabb: new Float32Array([-0.5, 9.5, -20.5, 0.5, 10.5, -19.5]),
+          bounded: true,
+          shadowCaster: true,
+        },
+      ],
+    );
+    expect(result).not.toBeNull();
+    if (result === null) return;
+    const cascade = result.cascades[0];
+    expect(cascade).toBeDefined();
+    if (cascade === undefined) return;
+    const decision = cascade.candidateDecisions?.[0];
+    expect(decision?.selected).toBe(true);
+    expect(cascade.casterRenderableIndices).toContain(10);
+    expect(decision?.lightSpaceBounds).toBeDefined();
+    if (decision?.lightSpaceBounds === undefined) return;
+
+    const receiverMaxZ = cascade.receiverLightBounds[5] ?? -Infinity;
+    const casterMaxZ = decision.lightSpaceBounds[5] ?? -Infinity;
+    const clipMaxZ = cascade.clipLightBounds[5] ?? -Infinity;
+    expect(casterMaxZ).toBeGreaterThan(receiverMaxZ);
+    expect(clipMaxZ).toBeGreaterThanOrEqual(casterMaxZ);
+    expect(result.volumes).toBe(result.cascades);
+    expect(cascade.rasterLightBounds).toBe(cascade.clipLightBounds);
+    const broadphase = cascade.casterBroadphaseWorldAabb;
+    const candidateBounds = new Float32Array([-0.5, 9.5, -20.5, 0.5, 10.5, -19.5]);
+    expect(broadphase[0]).toBeLessThanOrEqual(candidateBounds[0] ?? -Infinity);
+    expect(broadphase[1]).toBeLessThanOrEqual(candidateBounds[1] ?? -Infinity);
+    expect(broadphase[2]).toBeLessThanOrEqual(candidateBounds[2] ?? -Infinity);
+    expect(broadphase[3]).toBeGreaterThanOrEqual(candidateBounds[3] ?? Infinity);
+    expect(broadphase[4]).toBeGreaterThanOrEqual(candidateBounds[4] ?? Infinity);
+    expect(broadphase[5]).toBeGreaterThanOrEqual(candidateBounds[5] ?? Infinity);
+  });
+
+  it('keeps a stable-map edge caster that is outside the raw receiver AABB', () => {
+    const candidate = {
+      renderableIndex: 7,
+      worldId: 3,
+      entityKey: 11,
+      worldAabb: new Float32Array([-16.25, 7.75, -15.25, -15.75, 8.25, -14.75]),
+      bounded: true,
+      shadowCaster: true,
+    };
+    const result = computeDirectionalCsm(
+      LIGHT_DIRECTION,
+      { ...CONFIG, collectCandidateDecisions: true },
+      cameraData(),
+      [candidate],
+    );
+    expect(result).not.toBeNull();
+    if (result === null) return;
+    const cascade = result.cascades[0];
+    expect(cascade).toBeDefined();
+    if (cascade === undefined) return;
+    const decision = cascade.candidateDecisions?.find((entry) => entry.renderableIndex === 7);
+    expect(decision?.selected).toBe(true);
+    expect(decision?.reason).toBe('stable-clip-xy-overlap-and-toward-light');
+    expect(decision?.lightSpaceBounds).toBeDefined();
+    if (decision?.lightSpaceBounds === undefined) return;
+    // This is deliberately outside the unpadded receiver AABB. It remains
+    // inside the stable sphere/guard domain that owns the actual shadow map.
+    expect(decision.lightSpaceBounds[0] ?? 0).toBeGreaterThan(cascade.receiverLightBounds[1] ?? 0);
+    expect(decision.lightSpaceBounds[0] ?? 0).toBeLessThan(cascade.clipLightBounds[1] ?? 0);
+  });
+
+  it('excludes a caster fully outside the final stable clip domain', () => {
+    const candidate = {
+      renderableIndex: 8,
+      worldId: 3,
+      entityKey: 12,
+      worldAabb: new Float32Array([-30.25, -5.25, -40.25, -29.75, -4.75, -39.75]),
+      bounded: true,
+      shadowCaster: true,
+    };
+    const result = computeDirectionalCsm(
+      LIGHT_DIRECTION,
+      { ...CONFIG, collectCandidateDecisions: true },
+      cameraData(),
+      [candidate],
+    );
+    expect(result).not.toBeNull();
+    if (result === null) return;
+    const decision = result.cascades[0]?.candidateDecisions?.find(
+      (entry) => entry.renderableIndex === 8,
+    );
+    expect(decision?.selected).toBe(false);
+    expect(decision?.reason).toBe('outside-stable-clip-xy');
+  });
+
+  it('derives guard coverage from PCF footprint and map resolution', () => {
+    const pcf1 = halfExtent(extractWithShadowFields(1, 1024));
+    const pcf5 = halfExtent(extractWithShadowFields(5, 1024));
+    const lowResolution = halfExtent(extractWithShadowFields(3, 512));
+    const highResolution = halfExtent(extractWithShadowFields(3, 2048));
+
+    expect(pcf5).toBeGreaterThan(pcf1);
+    expect(lowResolution).toBeGreaterThan(highResolution);
+  });
+});

package/src/extract/__tests__/environment-source.test.ts

@@ -0,0 +1,105 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import {
+  Atmosphere,
+  DirectionalLight,
+  SkyboxBackground,
+  Skylight,
+  selectEnvironmentSource,
+} from '../../index';
+
+function spawnSun(world: World): void {
+  world
+    .spawn(
+      { component: Atmosphere, data: {} },
+      {
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0], color: [1, 0.9, 0.8], intensity: 4 },
+      },
+    )
+    .unwrap();
+}
+
+describe('environment source selector', () => {
+  it('uses only the resourceOwner World and preserves co-located normalized Sun facts', () => {
+    const resourceOwner = new World();
+    const cameraOwner = new World();
+    spawnSun(resourceOwner);
+    cameraOwner.spawn({ component: Skylight, data: {} }).unwrap();
+
+    const selected = selectEnvironmentSource({ resourceOwner, worldId: 7 });
+    expect(selected.ok).toBe(true);
+    if (selected.ok) {
+      expect(selected.value.kind).toBe('atmosphere');
+      if (selected.value.kind === 'atmosphere') {
+        expect(selected.value.worldId).toBe(7);
+        expect(selected.value.atmosphere.entity).toBe(selected.value.atmosphere.sun.entity);
+        expect([...selected.value.atmosphere.sun.direction]).toEqual([0, 1, 0]);
+        expect(selected.value.atmosphere.sun.illuminance).toBe(4);
+      }
+    }
+  });
+
+  it('does not classify a solid-color Skylight as an image source', () => {
+    const world = new World();
+    world.spawn({ component: Skylight, data: { color: [0.2, 0.3, 0.4], intensity: 0.5 } }).unwrap();
+
+    const selected = selectEnvironmentSource({ resourceOwner: world });
+    expect(selected.ok).toBe(true);
+    if (selected.ok) {
+      expect(selected.value.kind).toBe('none');
+      if (selected.value.kind === 'none') {
+        expect(selected.value.skylight?.equirectHandle).toBe(0);
+      }
+    }
+  });
+
+  it('classifies a non-zero equirect Skylight as image', () => {
+    const world = new World();
+    const equirect = world.allocSharedRef('EquirectAsset', { hdr: true });
+    world.spawn({ component: Skylight, data: { equirect } }).unwrap();
+
+    const selected = selectEnvironmentSource({ resourceOwner: world });
+    expect(selected.ok).toBe(true);
+    if (selected.ok) expect(selected.value.kind).toBe('image');
+  });
+
+  it('returns missing, conflict, and cardinality failures without precedence', () => {
+    const missing = new World();
+    missing.spawn({ component: Atmosphere, data: {} }).unwrap();
+    const missingResult = selectEnvironmentSource({ resourceOwner: missing });
+    expect(missingResult.ok).toBe(false);
+    if (!missingResult.ok) expect(missingResult.error.code).toBe('atmosphere-sun-missing');
+
+    const conflict = new World();
+    spawnSun(conflict);
+    const equirect = conflict.allocSharedRef('EquirectAsset', { hdr: true });
+    conflict.spawn({ component: Skylight, data: { equirect } }).unwrap();
+    const conflictResult = selectEnvironmentSource({ resourceOwner: conflict });
+    expect(conflictResult.ok).toBe(false);
+    if (!conflictResult.ok) expect(conflictResult.error.code).toBe('environment-source-conflict');
+
+    const cardinality = new World();
+    cardinality.spawn({ component: Atmosphere, data: {} }).unwrap();
+    cardinality.spawn({ component: Atmosphere, data: {} }).unwrap();
+    const cardinalityResult = selectEnvironmentSource({ resourceOwner: cardinality });
+    expect(cardinalityResult.ok).toBe(false);
+    if (
+      !cardinalityResult.ok &&
+      cardinalityResult.error.code === 'atmosphere-cardinality-invalid'
+    ) {
+      expect(cardinalityResult.error.detail.count).toBe(2);
+    }
+  });
+
+  it('does not treat a cameraOwner image as resourceOwner environment', () => {
+    const resourceOwner = new World();
+    const cameraOwner = new World();
+    const equirect = cameraOwner.allocSharedRef('EquirectAsset', { hdr: true });
+    cameraOwner.spawn({ component: SkyboxBackground, data: { equirect } }).unwrap();
+
+    const selected = selectEnvironmentSource({ resourceOwner });
+    expect(selected.ok).toBe(true);
+    if (selected.ok) expect(selected.value.kind).toBe('none');
+  });
+});

package/src/extract/__tests__/schema-readers.unit.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { readRenderSchemas } from '../schema-readers';
+
+describe('extract schema readers', () => {
+  it('reads mesh, light, and camera semantics from canonical rows', () => {
+    const handle = { id: 7 };
+    const frame = readRenderSchemas(
+      { assetHandle: handle },
+      { direction: new Float32Array([0, -1, 0]), intensity: 3 },
+      { projection: 1, near: 0.1, far: 50 },
+    );
+    expect(frame.mesh.assetHandle).toBe(handle);
+    expect(frame.light.direction).toEqual(new Float32Array([0, -1, 0]));
+    expect(frame.camera.projection).toBe(1);
+  });
+});