@forgeax/engine-render 0.1.2

package/src/__tests__/cluster-binner.test.ts

@@ -0,0 +1,272 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import {
+  bin,
+  calculateSphereClusterBounds,
+  clusterSpaceObjectAabb,
+  createClusterBinScratch,
+} from '../cluster-binner';
+
+function makeInputs() {
+  const view = mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]);
+  const proj = mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100);
+  const grid = { x: 4, y: 3, z: 4 };
+  return { view, proj, grid };
+}
+
+describe('cluster binner scratch path', () => {
+  it('preserves cluster-major light ordering across scratch reuse', () => {
+    const { view, proj, grid } = makeInputs();
+    const lights = [
+      { position: vec3.create(-1, 0, -4), range: 2 },
+      { position: vec3.create(1, 0, -5), range: 2 },
+    ];
+    const scratch = createClusterBinScratch();
+    const firstGrid = new Uint32Array(grid.x * grid.y * grid.z * 2);
+    const firstIndices = new Uint32Array(128);
+    const secondGrid = new Uint32Array(firstGrid.length);
+    const secondIndices = new Uint32Array(firstIndices.length);
+
+    const firstResult = bin(
+      lights,
+      view,
+      proj,
+      grid,
+      0.1,
+      100,
+      firstGrid,
+      firstIndices,
+      128,
+      scratch,
+    );
+    const secondResult = bin(
+      lights,
+      view,
+      proj,
+      grid,
+      0.1,
+      100,
+      secondGrid,
+      secondIndices,
+      128,
+      scratch,
+    );
+    expect(firstResult.ok).toBe(true);
+    expect(secondResult.ok).toBe(true);
+    if (firstResult.ok && secondResult.ok) {
+      expect(firstResult.value).toBeGreaterThan(0);
+      expect(secondResult.value).toBe(firstResult.value);
+    }
+    expect(Array.from(secondGrid)).toEqual(Array.from(firstGrid));
+    expect(Array.from(secondIndices)).toEqual(Array.from(firstIndices));
+  });
+
+  it('reports overflow before writing a partial cluster layout', () => {
+    const { view, proj, grid } = makeInputs();
+    const clusterGrid = new Uint32Array(grid.x * grid.y * grid.z * 2).fill(7);
+    const lightIndexList = new Uint32Array(8).fill(9);
+    const result = bin(
+      [{ position: vec3.create(0, 0, -4), range: 100 }],
+      view,
+      proj,
+      grid,
+      0.1,
+      100,
+      clusterGrid,
+      lightIndexList,
+      0,
+      createClusterBinScratch(),
+    );
+
+    expect(result.ok).toBe(false);
+    expect(clusterGrid.every((value) => value === 0)).toBe(true);
+    expect(lightIndexList.every((value) => value === 9)).toBe(true);
+  });
+
+  it('matches independently reconstructed counts and ascending light order', () => {
+    const { view, proj, grid } = makeInputs();
+    const lights = [
+      { position: vec3.create(-1, 0, -4), range: 2 },
+      { position: vec3.create(1, 0, -5), range: 2 },
+      { position: vec3.create(0, 1, -7), range: 1 },
+    ];
+    const clusterCount = grid.x * grid.y * grid.z;
+    const clusterGrid = new Uint32Array(clusterCount * 2);
+    const lightIndexList = new Uint32Array(256);
+    const result = bin(
+      lights,
+      view,
+      proj,
+      grid,
+      0.1,
+      100,
+      clusterGrid,
+      lightIndexList,
+      lightIndexList.length,
+      createClusterBinScratch(),
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const expectedCounts = new Uint32Array(clusterCount);
+    const expectedIndices: number[] = [];
+    const bounds = lights.map((light) =>
+      calculateSphereClusterBounds(
+        clusterSpaceObjectAabb(light.position, light.range, view, proj),
+        grid.x,
+        grid.y,
+        grid.z,
+        0.1,
+        100,
+      ),
+    );
+    for (let clusterIdx = 0; clusterIdx < clusterCount; clusterIdx++) {
+      const cz = Math.floor(clusterIdx / (grid.x * grid.y));
+      const rem = clusterIdx - cz * grid.x * grid.y;
+      const cy = Math.floor(rem / grid.x);
+      const cx = rem - cy * grid.x;
+      for (let lightIdx = 0; lightIdx < bounds.length; lightIdx++) {
+        const bound = bounds[lightIdx];
+        if (
+          bound !== undefined &&
+          cx >= bound.min.x &&
+          cx <= bound.max.x &&
+          cy >= bound.min.y &&
+          cy <= bound.max.y &&
+          cz >= bound.min.z &&
+          cz <= bound.max.z
+        ) {
+          expectedCounts[clusterIdx] = (expectedCounts[clusterIdx] ?? 0) + 1;
+        }
+      }
+    }
+
+    let expectedOffset = 0;
+    const expectedGrid = new Uint32Array(clusterCount * 2);
+    for (let clusterIdx = 0; clusterIdx < clusterCount; clusterIdx++) {
+      expectedGrid[clusterIdx * 2] = expectedOffset;
+      expectedGrid[clusterIdx * 2 + 1] = expectedCounts[clusterIdx] ?? 0;
+      for (let lightIdx = 0; lightIdx < bounds.length; lightIdx++) {
+        const bound = bounds[lightIdx];
+        if (
+          bound !== undefined &&
+          Math.floor(clusterIdx / (grid.x * grid.y)) >= bound.min.z &&
+          Math.floor(clusterIdx / (grid.x * grid.y)) <= bound.max.z &&
+          Math.floor((clusterIdx % (grid.x * grid.y)) / grid.x) >= bound.min.y &&
+          Math.floor((clusterIdx % (grid.x * grid.y)) / grid.x) <= bound.max.y &&
+          clusterIdx % grid.x >= bound.min.x &&
+          clusterIdx % grid.x <= bound.max.x
+        ) {
+          expectedIndices.push(lightIdx);
+        }
+      }
+      expectedOffset += expectedCounts[clusterIdx] ?? 0;
+    }
+
+    expect(result.value).toBe(expectedIndices.length);
+    expect(Array.from(clusterGrid)).toEqual(Array.from(expectedGrid));
+    expect(Array.from(lightIndexList.slice(0, result.value))).toEqual(expectedIndices);
+  });
+
+  it('reuses AABB and bounds outputs without changing helper results', () => {
+    const { view, proj, grid } = makeInputs();
+    const scratch = createClusterBinScratch();
+    const lights = [
+      { position: vec3.create(-1, 0, -4), range: 2 },
+      { position: vec3.create(1, 0, -5), range: 2 },
+      { position: vec3.create(0, 1, -7), range: 1 },
+    ];
+
+    for (const light of lights) {
+      const allocatingAabb = clusterSpaceObjectAabb(light.position, light.range, view, proj);
+      const reusedAabb = clusterSpaceObjectAabb(
+        light.position,
+        light.range,
+        view,
+        proj,
+        scratch.aabbOutput,
+      );
+      const allocatingBounds = calculateSphereClusterBounds(
+        allocatingAabb,
+        grid.x,
+        grid.y,
+        grid.z,
+        0.1,
+        100,
+      );
+      const reusedBounds = calculateSphereClusterBounds(
+        reusedAabb,
+        grid.x,
+        grid.y,
+        grid.z,
+        0.1,
+        100,
+        scratch.boundsOutput,
+      );
+
+      expect(Array.from(reusedAabb.min)).toEqual(Array.from(allocatingAabb.min));
+      expect(Array.from(reusedAabb.max)).toEqual(Array.from(allocatingAabb.max));
+      expect(reusedBounds).toEqual(allocatingBounds);
+      expect(reusedAabb).toBe(scratch.aabbOutput);
+      expect(reusedBounds).toBe(scratch.boundsOutput);
+    }
+  });
+
+  it('can reserve the ordered ranges without materializing the CPU membership list', () => {
+    const { view, proj, grid } = makeInputs();
+    const clusterGrid = new Uint32Array(grid.x * grid.y * grid.z * 2);
+    const lightIndexList = new Uint32Array(256).fill(0xcafe);
+    const result = bin(
+      [{ position: vec3.create(0, 0, -4), range: 2 }],
+      view,
+      proj,
+      grid,
+      0.1,
+      100,
+      clusterGrid,
+      lightIndexList,
+      lightIndexList.length,
+      createClusterBinScratch(),
+      undefined,
+      { writeMembership: false },
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.ok && result.value).toBeGreaterThan(0);
+    expect(clusterGrid.some((value) => value > 0)).toBe(true);
+    expect(lightIndexList.every((value) => value === 0xcafe)).toBe(true);
+  });
+
+  it('reports the bounded phases around the existing passes', () => {
+    const { view, proj, grid } = makeInputs();
+    const phases: string[] = [];
+    const result = bin(
+      [{ position: vec3.create(0, 0, -4), range: 2 }],
+      view,
+      proj,
+      grid,
+      0.1,
+      100,
+      new Uint32Array(grid.x * grid.y * grid.z * 2),
+      new Uint32Array(128),
+      128,
+      createClusterBinScratch(),
+      (phase, action) => {
+        phases.push(phase);
+        return action();
+      },
+    );
+
+    expect(result.ok).toBe(true);
+    expect(phases).toEqual([
+      'light-bounds-and-occupancy',
+      'light-bounds-and-occupancy/light-aabb',
+      'light-bounds-and-occupancy/cluster-occupancy',
+      'cluster-reserve',
+      'light-index-write',
+      'light-index-write/bounds-read',
+      'light-index-write/cluster-write',
+    ]);
+  });
+});

package/src/__tests__/cluster-grid-default-surface.unit.test.ts

@@ -0,0 +1,17 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_CLUSTER_GRID } from '../hdrp-pipeline';
+
+const ownerSource = readFileSync(new URL('../hdrp-pipeline.ts', import.meta.url), 'utf8');
+const recordSource = readFileSync(new URL('../record/frame-lighting.ts', import.meta.url), 'utf8');
+
+describe('cluster grid default owner', () => {
+  it('keeps both record-stage fallbacks on the pipeline owner', () => {
+    expect(DEFAULT_CLUSTER_GRID).toEqual({ x: 16, y: 9, z: 24 });
+    expect(
+      ownerSource.match(/export const DEFAULT_CLUSTER_GRID\s*=\s*\{ x: 16, y: 9, z: 24 \}/g),
+    ).toHaveLength(1);
+    expect(recordSource.match(/clusterGrid \?\? DEFAULT_CLUSTER_GRID/g)).toHaveLength(2);
+    expect(recordSource).not.toMatch(/clusterGrid \?\? \{\s*x: 16,\s*y: 9,\s*z: 24,\s*\}/);
+  });
+});

package/src/__tests__/construct-renderer-identity.unit.test.ts

@@ -0,0 +1,10 @@
+import * as render from '@forgeax/engine-render';
+import { constructRenderer as internalConstructRenderer } from '@forgeax/engine-render/internal/construct-renderer';
+import { describe, expect, it } from 'vitest';
+
+describe('construct-renderer internal entry', () => {
+  it('keeps construction out of the public barrel', () => {
+    expect('constructRenderer' in render).toBe(false);
+    expect(internalConstructRenderer).toEqual(expect.any(Function));
+  });
+});

package/src/__tests__/direct-extract-consumer-contract.test-d.ts

@@ -0,0 +1,34 @@
+import type { World } from '@forgeax/engine-ecs';
+import {
+  extractFrame,
+  extractFrames,
+  type PreparedExtractContext,
+} from '@forgeax/engine-render/internal';
+import { expectTypeOf } from 'vitest';
+import type {
+  DerivedMaterialSlotProjection,
+  DerivedMaterialSlotProjectionInput,
+} from '../extract/material-interface.js';
+
+declare const input: DerivedMaterialSlotProjectionInput;
+declare const projection: DerivedMaterialSlotProjection;
+declare const world: World;
+declare const prepared: PreparedExtractContext;
+
+extractFrames([world], 0);
+extractFrame(world, prepared);
+
+// Freshness belongs to extractFrames. A per-world kernel call must not compile
+// without the context produced by the preparation seam.
+// @ts-expect-error extractFrame requires prepared context
+extractFrame(world);
+// @ts-expect-error null is not a prepared context
+extractFrame(world, null);
+
+expectTypeOf(input.schema).toMatchTypeOf<
+  readonly { readonly name: string; readonly type: string }[]
+>();
+expectTypeOf(projection.derivedInterface.layoutIdentity).toBeString();
+expectTypeOf(projection.coordinates).toMatchTypeOf<
+  ReadonlyMap<string, { readonly physicalUvScale: readonly [number, number] }>
+>();

package/src/__tests__/direct-light-snapshot.unit.test.ts

@@ -0,0 +1,71 @@
+import { readFile } from 'node:fs/promises';
+import type { Vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import { packLightSlot, packSpotLight } from '../light-buffer-layout';
+import type { SpotLightSnapshot } from '../render-system-extract';
+
+const snapshot: SpotLightSnapshot = {
+  kind: 'spot',
+  entity: 7,
+  position: new Float32Array([0, 2, 0]) as Vec3,
+  direction: new Float32Array([0, 1, 0]) as Vec3,
+  color: new Float32Array([2, 1, 0.5]) as Vec3,
+  intensity: 2,
+  invRangeSquared: 0.01,
+  cosInner: 0.98,
+  cosOuter: 0.7,
+  castShadow: true,
+  lightViewProj: new Float32Array(16),
+  mapSize: 2048,
+  nearPlane: 0.1,
+  farPlane: 50,
+  shadowAtlasTile: 0,
+};
+
+describe('one direct-light snapshot proof', () => {
+  it('passes the same snapshot identity to URP and HDRP buffer owners', () => {
+    const consumed: SpotLightSnapshot[] = [];
+    const consume = (value: SpotLightSnapshot) => {
+      consumed.push(value);
+      return {
+        urp: packSpotLight(value),
+        hdrp: packLightSlot(value),
+      };
+    };
+
+    const packed = consume(snapshot);
+
+    expect(consumed).toEqual([snapshot]);
+    expect(packed.urp[8]).toBe(0);
+    expect(packed.urp[9]).toBe(1);
+    expect(packed.hdrp[8]).toBe(0);
+    expect(packed.hdrp[9]).toBe(1);
+    expect(new Int32Array(packed.hdrp.buffer)[13]).toBe(0);
+  });
+
+  it('uses identical LightSlot bytes for storage and uniform transport', () => {
+    const storage = packLightSlot(snapshot);
+    const uniform = packLightSlot(snapshot);
+
+    expect(new Uint8Array(storage.buffer)).toEqual(new Uint8Array(uniform.buffer));
+    expect(new Int32Array(storage.buffer)[13]).toBe(snapshot.shadowAtlasTile);
+  });
+
+  it('keeps extract and shader owners single-source', async () => {
+    const extract = await readFile(new URL('../render-system-extract.ts', import.meta.url), 'utf8');
+    const lighting = await readFile(
+      new URL('../record/frame-lighting.ts', import.meta.url),
+      'utf8',
+    );
+    const shader = await readFile(
+      new URL('../../../shader/src/hdrp-cluster-forward.wgsl', import.meta.url),
+      'utf8',
+    );
+
+    expect(extract.match(/const spotLightQuery =/g)).toHaveLength(1);
+    expect(extract).toContain('direction: dirN');
+    expect(lighting).toContain('packLightSlot(pl');
+    expect(lighting).toContain('packLightSlot(sl)');
+    expect(shader).not.toContain('normalize(light.direction.xyz)');
+  });
+});

package/src/__tests__/directional-shadow-probe-atlas-layout.unit.test.ts

@@ -0,0 +1,18 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const rendererFactorySource = readFileSync(
+  new URL('../renderer/renderer-factory.ts', import.meta.url),
+  'utf8',
+);
+
+describe('directional shadow probe atlas layout', () => {
+  it('matches the compact host atlas rows instead of assuming a square atlas', () => {
+    expect(rendererFactorySource).toMatch(/let rows : u32 = \(count \+ columns - 1u\) \/ columns;/);
+    expect(rendererFactorySource).toMatch(
+      /let tileScale = vec2<f32>\(1\.0\) \/ vec2<f32>\(grid\);/,
+    );
+    expect(rendererFactorySource).toMatch(/let uv = tileUv \* tileScale \+ tileOrigin;/);
+    expect(rendererFactorySource).not.toMatch(/let uv = tileUv \* inv \+ tileOrigin;/);
+  });
+});

package/src/__tests__/environment-inspection.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import {
+  beginEnvironmentGeneration,
+  createEnvironmentGenerationState,
+} from '../environment/generation';
+import { inspectEnvironmentGeneration, projectFogEnvironment } from '../environment/inspection';
+
+describe('environment inspection', () => {
+  it('projects bounded lifecycle, source, cost, failure, and TAA facts', () => {
+    const state = createEnvironmentGenerationState('device-a');
+    const attempt = beginEnvironmentGeneration(state, { signature: 'desired', bytes: 128 });
+    const inspection = inspectEnvironmentGeneration(state, {
+      sourceWorldId: 3,
+      sourceEntity: 4,
+      rebuild: { passCount: 42, timeMs: 2 },
+      taa: {
+        activeSignature: undefined,
+        publishCount: 0,
+        resetCount: 0,
+        lastResetReason: undefined,
+      },
+    });
+    expect(inspection).toMatchObject({
+      state: 'building',
+      source: { worldId: 3, entity: 4 },
+      desiredSignature: 'desired',
+      deviceGeneration: 'device-a',
+      rebuild: { passCount: 42, timeMs: 2 },
+      taa: { publishCount: 0, resetCount: 0 },
+    });
+    expect(Object.keys(inspection)).not.toEqual(expect.arrayContaining(['handle', 'cache']));
+    attempt.fail('build');
+    expect(inspectEnvironmentGeneration(state).state).toBe('failed');
+  });
+
+  it('keeps the future Fog seam readonly and source-derived', () => {
+    const projection = projectFogEnvironment({
+      activeSignature: 'active',
+      sunDirection: [0, 0, -1],
+      illuminance: 10,
+    });
+    expect(Object.isFrozen(projection)).toBe(true);
+    expect(projection.activeSignature).toBe('active');
+  });
+});