@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/__tests__/callback-inference.test-d.ts

@@ -0,0 +1,8 @@
+import type { FrameObservationRequest, FrameReceipt, Renderer } from '../render-contract';
+
+const consume = (
+  renderer: Renderer,
+  receipt: FrameReceipt,
+  request: FrameObservationRequest,
+): Promise<boolean> => renderer.observe(receipt, request).then((result) => result.ok);
+void consume;

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,20 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_CLUSTER_GRID } from '../pipeline/standard-profile';
+
+const ownerSource = readFileSync(
+  new URL('../pipeline/standard-profile.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 all 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(3);
+    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,23 @@
+import * as render from '@forgeax/engine-render';
+import {
+  constructRendererHost as internalConstructRendererHost,
+  type RendererHostAssembly,
+} from '@forgeax/engine-render/internal/construct-renderer';
+import { describe, expect, it } from 'vitest';
+import type { RenderError } from '../errors/render';
+import type { RenderResult } from '../render-contract';
+
+describe('construct-renderer internal entry', () => {
+  it('keeps construction out of the public barrel', () => {
+    expect('constructRenderer' in render).toBe(false);
+    expect(internalConstructRendererHost).toEqual(expect.any(Function));
+  });
+
+  it('freezes the only construct seam as a structured Result factory', () => {
+    type Return = ReturnType<typeof internalConstructRendererHost>;
+    type Expected = Promise<RenderResult<RendererHostAssembly, RenderError>>;
+    // This assertion is intentionally red until construction stops rejecting
+    // and returns the narrow Result contract.
+    expect(null as unknown as Return satisfies Expected).toBeNull();
+  });
+});

package/src/__tests__/device-scope-lifecycle.unit.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DeviceScope,
+  type LifecycleResourceSpec,
+  LifecycleTransaction,
+} from '../device/device-scope';
+
+function spec(
+  kind: LifecycleResourceSpec<unknown>['kind'],
+  order: string[],
+  index: number,
+  failAt?: number,
+): LifecycleResourceSpec<unknown> {
+  return {
+    kind,
+    create: () => {
+      if (failAt === index) throw new Error(`create-${kind}`);
+      order.push(`create:${kind}`);
+      return { kind };
+    },
+    cleanup: () => {
+      order.push(`cleanup:${kind}`);
+    },
+  };
+}
+
+describe('DeviceScope lifecycle transaction', () => {
+  it('rolls back the first N-1 resources in reverse order and keeps the primary error', async () => {
+    const scope = DeviceScope.create(7, 'renderer');
+    const order: string[] = [];
+    const transaction = new LifecycleTransaction(scope, { failureAt: 4 });
+    transaction.add(spec('listener', order, 1));
+    transaction.add(spec('surface', order, 2));
+    transaction.add(spec('shader', order, 3));
+    transaction.add(spec('pipeline', order, 4, 4));
+
+    const result = await transaction.commit();
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.primary.code).toBe('lifecycle-construction-failed');
+      expect(result.error.primary.detail.owner).toBe('renderer');
+      expect(result.error.cleanupFailures).toEqual([]);
+      expect(result.error.receipt.generation).toBe(7);
+    }
+    expect(order).toEqual([
+      'create:listener',
+      'create:surface',
+      'create:shader',
+      'cleanup:shader',
+      'cleanup:surface',
+      'cleanup:listener',
+    ]);
+    expect(scope.resourceDelta()).toBe(0);
+    expect(scope.state).toBe('active');
+  });
+
+  it('collects cleanup failures without changing the primary error or resource delta', async () => {
+    const scope = DeviceScope.create(8, 'renderer');
+    const transaction = new LifecycleTransaction(scope, { failureAt: 3 });
+    transaction.add({
+      kind: 'buffer',
+      create: () => ({ id: 'buffer' }),
+      cleanup: () => {
+        throw new Error('buffer-cleanup');
+      },
+    });
+    transaction.add({
+      kind: 'texture',
+      create: () => ({ id: 'texture' }),
+      cleanup: () => undefined,
+    });
+    transaction.add({
+      kind: 'binding',
+      create: () => {
+        throw new Error('binding-create');
+      },
+      cleanup: () => undefined,
+    });
+
+    const result = await transaction.commit();
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.primary.detail.operation).toBe('create');
+      expect(result.error.primary.detail.resourceKind).toBe('binding');
+      expect(result.error.cleanupFailures).toHaveLength(1);
+      expect(result.error.cleanupFailures[0]?.resourceKind).toBe('buffer');
+    }
+    expect(scope.resourceDelta()).toBe(0);
+  });
+
+  it('publishes a replacement only after complete success and retires the old scope', async () => {
+    const current = DeviceScope.create(10, 'renderer');
+    const oldRef = current.ref('shader', { id: 'old' });
+
+    const replacementResult = await current.replace(11, [
+      {
+        kind: 'shader',
+        create: () => ({ id: 'new' }),
+        cleanup: () => undefined,
+      },
+    ]);
+
+    expect(replacementResult.ok).toBe(true);
+    if (replacementResult.ok) {
+      expect(current.state).toBe('retired');
+      expect(replacementResult.value.state).toBe('active');
+      expect(replacementResult.value.parent).toBe(current);
+      expect(oldRef.isStale(replacementResult.value)).toBe(true);
+    }
+  });
+
+  it('keeps the current scope active when replacement construction is lost', async () => {
+    const current = DeviceScope.create(20, 'renderer');
+    const result = await current.replace(21, [
+      {
+        kind: 'surface',
+        create: () => {
+          throw new Error('replacement-loss');
+        },
+        cleanup: () => undefined,
+      },
+    ]);
+
+    expect(result.ok).toBe(false);
+    expect(current.state).toBe('active');
+    expect(current.generation).toBe(20);
+    expect(current.resourceDelta()).toBe(0);
+  });
+
+  it('makes dispose win over an in-flight construction and terminalizes pending work', async () => {
+    const scope = DeviceScope.create(30, 'renderer');
+    let resolveCreate: ((value: { id: string }) => void) | undefined;
+    const transaction = new LifecycleTransaction(scope);
+    transaction.add({
+      kind: 'post-effect',
+      create: () => new Promise<{ id: string }>((resolve) => (resolveCreate = resolve)),
+      cleanup: () => undefined,
+    });
+
+    const pending = transaction.commit();
+    scope.dispose();
+    resolveCreate?.({ id: 'late' });
+    const result = await pending;
+
+    expect(result.ok).toBe(false);
+    expect(scope.state).toBe('disposed');
+    expect(scope.resourceDelta()).toBe(0);
+  });
+});

package/src/__tests__/device-scope-stale-matrix.unit.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { DEVICE_RESOURCE_KINDS, DeviceScope } from '../device/device-scope';
+
+describe('DeviceScope stale resource matrix', () => {
+  it('covers every device-bound resource family through one generation fence', () => {
+    const current = DeviceScope.create(40, 'renderer');
+    const replacement = DeviceScope.create(41, 'renderer');
+
+    for (const kind of DEVICE_RESOURCE_KINDS) {
+      const ref = current.ref(kind, { kind });
+      expect(ref.kind).toBe(kind);
+      expect(ref.isCurrent(current)).toBe(true);
+      expect(ref.isStale(replacement)).toBe(true);
+      expect(replacement.accepts(ref)).toBe(false);
+    }
+
+    expect(DEVICE_RESOURCE_KINDS).toEqual([
+      'listener',
+      'surface',
+      'shader',
+      'pipeline',
+      'buffer',
+      'texture',
+      'binding',
+      'scene-table',
+      'feature',
+      'post-effect',
+    ]);
+  });
+
+  it('does not publish stale alive state after retire or abandon', () => {
+    const retired = DeviceScope.create(50, 'renderer');
+    retired.retire();
+    const abandoned = DeviceScope.create(51, 'renderer');
+    abandoned.abandon();
+
+    expect(retired.state).toBe('retired');
+    expect(abandoned.state).toBe('abandoned');
+    expect(retired.isAlive()).toBe(false);
+    expect(abandoned.isAlive()).toBe(false);
+  });
+});

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

@@ -0,0 +1,23 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { CatalogDelta } from '@forgeax/engine-types';
+import { expectTypeOf } from 'vitest';
+import type { PreparedExtractContext } from '../render-system-extract';
+import { extractFrame, extractFrames } from '../render-system-extract';
+
+declare const delta: CatalogDelta;
+
+expectTypeOf(delta.scopeId).toEqualTypeOf<string | undefined>();
+expectTypeOf(delta.generation).toEqualTypeOf<number | undefined>();
+
+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);

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

@@ -0,0 +1,61 @@
+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',
+  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: false,
+  lightViewProj: undefined,
+  mapSize: 2048,
+  nearPlane: 0.1,
+  farPlane: 50,
+  shadowAtlasTile: -1,
+};
+
+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);
+  });
+
+  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)');
+  });
+});