@forgeax/engine-render 0.1.4 → 0.1.6

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

@@ -1,391 +0,0 @@
-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

@@ -1,105 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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);
-  });
-});