@forgeax/engine-render 0.1.19 → 0.1.21

package/src/__tests__/standard-lighting-inspection.integration.test.ts

@@ -0,0 +1,138 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import {
+  inspectStandardClusterTransport,
+  inspectStandardLighting,
+} from '../pipeline/standard-lighting/inspection';
+import {
+  prepareStandardLighting,
+  type StandardLightFrame,
+} from '../pipeline/standard-lighting/prepare';
+import { selectStandardClusterTransport } from '../pipeline/standard-lighting/transport';
+
+function prepared(localCount: number) {
+  const frame: StandardLightFrame = {
+    directional: undefined,
+    local: Array.from({ length: localCount }, (_, index) => ({
+      kind: index % 2 === 0 ? ('point' as const) : ('spot' as const),
+      shadowed: false,
+      position: vec3.create((index % 4) - 1.5, 0, -4 - (index % 8)),
+      range: 2,
+    })),
+    view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+    projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+    near: 0.1,
+    far: 100,
+    grid: { x: 4, y: 3, z: 4 },
+    lightCount: 256,
+    renderPath: 'forward',
+  };
+  const result = prepareStandardLighting(frame);
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+describe('Standard lighting inspection provenance', () => {
+  it('reports facts from the selected prepared transport, not a profile constant', () => {
+    const preparedFrame = prepared(33);
+    const selected = selectStandardClusterTransport(
+      { compute: false, storageBuffer: true, membershipPipelineReady: false },
+      preparedFrame,
+    );
+    expect(selected.ok).toBe(true);
+    if (!selected.ok) return;
+
+    expect(inspectStandardClusterTransport(selected.value, preparedFrame)).toEqual({
+      renderPath: 'forward',
+      transport: 'cpu-storage',
+      producer: 'cpu',
+      requested: 33,
+      admitted: 33,
+      shadowed: 0,
+      maxLights: 256,
+      indexCount: preparedFrame.membershipEntryCount,
+      occupied: selected.value.occupiedClusterCount,
+      clusterGridBytes: preparedFrame.layout.clusterGridU32Length * 4,
+      lightIndexListBytes: preparedFrame.membershipEntryCount * 4,
+      lightDataBytes: 33 * 64,
+      lightBoundsBytes: preparedFrame.lightBounds.byteLength,
+      grid: preparedFrame.layout.grid,
+    });
+  });
+
+  it('publishes an explicit not-required inspection for a successful zero-local frame', () => {
+    const result = prepareStandardLighting({
+      directional: undefined,
+      local: [],
+      view: mat4.create(),
+      projection: mat4.create(),
+      near: 0.1,
+      far: 100,
+      grid: { x: 4, y: 3, z: 4 },
+      lightCount: 1,
+      renderPath: 'forward',
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const inspection = inspectStandardLighting({ kind: 'no-local-lights', prepared: result.value });
+    expect(inspection).toEqual({
+      renderPath: 'forward',
+      transport: 'not-required',
+      producer: 'none',
+      requested: 0,
+      admitted: 0,
+      shadowed: 0,
+      maxLights: 1,
+      indexCount: 0,
+      occupied: 0,
+      clusterGridBytes: 0,
+      lightIndexListBytes: 0,
+      lightDataBytes: 0,
+      lightBoundsBytes: 0,
+      grid: result.value.layout.grid,
+    });
+  });
+
+  it('preserves deferred path, shadow admission, and profile light budget', () => {
+    const frame: StandardLightFrame = {
+      directional: undefined,
+      local: [
+        {
+          kind: 'point',
+          shadowed: true,
+          position: vec3.create(0, 0, -4),
+          range: 2,
+        },
+      ],
+      view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+      projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+      near: 0.1,
+      far: 100,
+      grid: { x: 4, y: 3, z: 4 },
+      lightCount: 32,
+      renderPath: 'deferred',
+    };
+    const preparedFrame = prepareStandardLighting(frame);
+    expect(preparedFrame.ok).toBe(true);
+    if (!preparedFrame.ok) return;
+    const selected = selectStandardClusterTransport(
+      { compute: true, storageBuffer: true, membershipPipelineReady: true },
+      preparedFrame.value,
+    );
+    expect(selected.ok).toBe(true);
+    if (!selected.ok) return;
+    expect(
+      inspectStandardLighting({
+        kind: 'clustered',
+        prepared: preparedFrame.value,
+        transport: selected.value,
+      }),
+    ).toMatchObject({
+      renderPath: 'deferred',
+      transport: 'compute-storage',
+      producer: 'gpu',
+      shadowed: 1,
+      maxLights: 32,
+    });
+  });
+});

package/src/__tests__/standard-lighting-ssot.unit.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { STANDARD_CLUSTER_LAYOUT } from '../pipeline/standard-lighting/layout';
+import { CLUSTER_GRID_STRIDE_U32, LIGHT_INDEX_LIST_CAPACITY } from '../pipeline/standard-profile';
+
+describe('Standard lighting layout SSOT', () => {
+  it('derives the transport storage sizes from one cluster layout', () => {
+    expect(STANDARD_CLUSTER_LAYOUT.clusterGridStrideU32).toBe(CLUSTER_GRID_STRIDE_U32);
+    expect(STANDARD_CLUSTER_LAYOUT.lightIndexListCapacity).toBe(LIGHT_INDEX_LIST_CAPACITY);
+    expect(STANDARD_CLUSTER_LAYOUT.clusterGridU32Length).toBe(
+      STANDARD_CLUSTER_LAYOUT.clusterCount * STANDARD_CLUSTER_LAYOUT.clusterGridStrideU32,
+    );
+  });
+
+  it('does not introduce a second light-index budget', () => {
+    expect(Object.keys(STANDARD_CLUSTER_LAYOUT)).not.toContain('maxLightIndexListCapacity');
+    expect(STANDARD_CLUSTER_LAYOUT.lightIndexListCapacity).toBe(LIGHT_INDEX_LIST_CAPACITY);
+  });
+});

package/src/__tests__/standard-lighting-write.unit.test.ts

@@ -0,0 +1,377 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { RhiError, err as rhiErr, ok as rhiOk } from '@forgeax/engine-rhi';
+import { RhiNullAdapter } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import {
+  createHdrpClusterMembershipBindGroupLayoutDescriptor,
+  getOrCreateHdrpBuffers,
+} from '../hdrp-buffers';
+import { prepareStandardLighting } from '../pipeline/standard-lighting/prepare';
+import { selectStandardClusterTransport } from '../pipeline/standard-lighting/transport';
+import { writeHdrpClusterAndSsaoBuffers } from '../record/frame-lighting';
+import type { RenderFrameState } from '../record/frame-snapshot';
+import type { RenderSystemInternals, RenderSystemRuntime } from '../record/render-context';
+import type { CameraSnapshot } from '../render-contract';
+
+function camera(): CameraSnapshot {
+  return {
+    position: vec3.create(0, 0, 5),
+    world: mat4.create(),
+    fov: Math.PI / 4,
+    aspect: 1,
+    near: 0.1,
+    far: 100,
+    projection: 'perspective',
+    orthoLeft: -1,
+    orthoRight: 1,
+    orthoBottom: -1,
+    orthoTop: 1,
+    tonemap: 'none',
+    exposure: 1,
+    whitePoint: 4,
+    antialias: 'none',
+    bloom: 'off',
+    bloomThreshold: 1,
+    bloomIntensity: 1,
+    bloomBlurRadius: 4,
+    clearColor: [0, 0, 0, 1],
+  };
+}
+
+function internalsWithFirstWriteFailure() {
+  const writes: string[] = [];
+  const payloads = new Map<string, Uint8Array>();
+  const errors: unknown[] = [];
+  const device = {
+    caps: { storageBuffer: true, compute: false, backendKind: 'webgpu' },
+    limits: { maxStorageBufferBindingSize: 1024 * 1024 * 1024 },
+    queue: {
+      writeBuffer(buffer: { readonly label?: string }, _offset: number, data: ArrayBufferView) {
+        const label = buffer.label ?? 'unknown';
+        writes.push(label);
+        payloads.set(label, new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice());
+        return writes.length === 1
+          ? rhiErr(
+              new RhiError({
+                code: 'webgpu-runtime-error',
+                expected: 'upload succeeds',
+                hint: 'test failure',
+              }),
+            )
+          : rhiOk(undefined);
+      },
+      onSubmittedWorkDone: async () => undefined,
+    },
+    createBuffer: (descriptor: { readonly label?: string }) =>
+      rhiOk({ label: descriptor.label } as never),
+    createBindGroupLayout: () => rhiOk({} as never),
+    destroyBuffer: () => rhiOk(undefined),
+  } as unknown as RhiDevice;
+  return {
+    writes,
+    payloads,
+    errors,
+    internals: {
+      device,
+      errorRegistry: { fire: (error: unknown) => errors.push(error) },
+      standardProfile: undefined,
+    },
+  };
+}
+
+describe('Standard Cluster upload ownership', () => {
+  it('returns device-operation-failed instead of publishing after a required upload fails', () => {
+    const source = {
+      kind: 'point' as const,
+      position: vec3.create(0, 0, -4),
+      color: vec3.create(1, 1, 1),
+      intensity: 1,
+      invRangeSquared: 0.25,
+      shadowAtlasLayer: -1,
+    };
+    const prepared = prepareStandardLighting({
+      directional: undefined,
+      local: [{ kind: 'point', shadowed: false, position: source.position, range: 2, source }],
+      view: mat4.create(),
+      projection: mat4.create(),
+      near: 0.1,
+      far: 100,
+      grid: { x: 4, y: 3, z: 4 },
+      lightCount: 1,
+      renderPath: 'forward',
+    });
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+    const transport = selectStandardClusterTransport(
+      { compute: false, storageBuffer: true, membershipPipelineReady: false },
+      prepared.value,
+    );
+    expect(transport.ok).toBe(true);
+    if (!transport.ok) return;
+    const { internals, writes, errors } = internalsWithFirstWriteFailure();
+    const result = writeHdrpClusterAndSsaoBuffers(
+      internals as never,
+      { hdrpClusterMembership: null, installedPipelineConfig: undefined } as never,
+      camera(),
+      prepared.value,
+      transport.value,
+    );
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('device-operation-failed');
+    expect(writes).toHaveLength(1);
+    expect(errors).toEqual([]);
+  });
+
+  it('rejects local lights without storage and performs no upload', () => {
+    const source = {
+      kind: 'point' as const,
+      position: vec3.create(0, 0, -4),
+      color: vec3.create(1, 1, 1),
+      intensity: 1,
+      invRangeSquared: 0.25,
+      shadowAtlasLayer: -1,
+    };
+    const prepared = prepareStandardLighting({
+      directional: undefined,
+      local: [{ kind: 'point', shadowed: false, position: source.position, range: 2, source }],
+      view: mat4.create(),
+      projection: mat4.create(),
+      near: 0.1,
+      far: 100,
+      grid: { x: 4, y: 3, z: 4 },
+      lightCount: 1,
+      renderPath: 'forward',
+    });
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+    const transport = selectStandardClusterTransport(
+      { compute: true, storageBuffer: false, membershipPipelineReady: false },
+      prepared.value,
+    );
+    expect(transport.ok).toBe(false);
+    if (transport.ok) return;
+    expect(transport.error.code).toBe('standard-cluster-transport-unavailable');
+  });
+
+  it('grows the persistent bundle atomically and retires the old buffers after the fence', async () => {
+    const adapter = new RhiNullAdapter();
+    const deviceResult = await adapter.requestDevice();
+    expect(deviceResult.ok).toBe(true);
+    if (!deviceResult.ok) return;
+    const baseDevice = deviceResult.value;
+    let releaseFence!: () => void;
+    const fence = new Promise<undefined>((resolve) => {
+      releaseFence = () => resolve(undefined);
+    });
+    const device = {
+      caps: baseDevice.caps,
+      features: baseDevice.features,
+      limits: baseDevice.limits,
+      lost: baseDevice.lost,
+      queue: {
+        writeBuffer: baseDevice.queue.writeBuffer.bind(baseDevice.queue),
+        onSubmittedWorkDone: () => fence,
+      },
+      createBuffer: baseDevice.createBuffer.bind(baseDevice),
+      createBindGroupLayout: baseDevice.createBindGroupLayout.bind(baseDevice),
+      destroyBuffer: baseDevice.destroyBuffer.bind(baseDevice),
+    } as unknown as RhiDevice;
+    const errors: unknown[] = [];
+    const runtime = {
+      device,
+      errorRegistry: { fire: (error: unknown) => errors.push(error) },
+    } as unknown as RenderSystemRuntime;
+
+    const small = getOrCreateHdrpBuffers(runtime, { x: 2, y: 2, z: 2 });
+    expect(small).not.toBeNull();
+    if (small === null) return;
+    expect(getOrCreateHdrpBuffers(runtime, { x: 1, y: 1, z: 1 })).toBe(small);
+
+    const grown = getOrCreateHdrpBuffers(runtime, { x: 4, y: 4, z: 4 });
+    expect(grown).not.toBeNull();
+    if (grown === null) return;
+    expect(grown).not.toBe(small);
+    expect(grown.clusterGridBytes).toBeGreaterThan(small.clusterGridBytes);
+
+    await Promise.resolve();
+    const ledger = baseDevice as unknown as {
+      readonly bookkeeper: { isDestroyed(handle: unknown): boolean };
+    };
+    expect(ledger.bookkeeper.isDestroyed(small.lightDataBuffer)).toBe(false);
+    expect(ledger.bookkeeper.isDestroyed(small.clusterGridBuffer)).toBe(false);
+    releaseFence();
+    await Promise.resolve();
+    expect(ledger.bookkeeper.isDestroyed(small.lightDataBuffer)).toBe(true);
+    expect(ledger.bookkeeper.isDestroyed(small.clusterGridBuffer)).toBe(true);
+    expect(ledger.bookkeeper.isDestroyed(grown.lightDataBuffer)).toBe(false);
+    expect(errors).toEqual([]);
+  });
+
+  it('retires a cached bundle when the runtime switches devices', async () => {
+    const adapter = new RhiNullAdapter();
+    const first = await adapter.requestDevice();
+    const second = await adapter.requestDevice();
+    expect(first.ok && second.ok).toBe(true);
+    if (!first.ok || !second.ok) return;
+    const errors: unknown[] = [];
+    const runtime = {
+      device: first.value,
+      errorRegistry: { fire: (error: unknown) => errors.push(error) },
+    } as unknown as RenderSystemRuntime & { device: RhiDevice };
+    const old = getOrCreateHdrpBuffers(runtime, { x: 2, y: 2, z: 2 });
+    expect(old).not.toBeNull();
+    if (old === null) return;
+    runtime.device = second.value;
+    const next = getOrCreateHdrpBuffers(runtime, { x: 2, y: 2, z: 2 });
+    expect(next).not.toBeNull();
+    const ledger = first.value as unknown as {
+      readonly bookkeeper: { isDestroyed(handle: unknown): boolean };
+    };
+    await Promise.resolve();
+    expect(ledger.bookkeeper.isDestroyed(old.lightDataBuffer)).toBe(true);
+    expect(errors).toEqual([]);
+  });
+
+  it('rebuilds the membership bind group when a same-device grid grows', () => {
+    const adapter = new RhiNullAdapter();
+    return adapter.requestDevice().then((deviceResult) => {
+      expect(deviceResult.ok).toBe(true);
+      if (!deviceResult.ok) return;
+      const device = deviceResult.value;
+      const errors: unknown[] = [];
+      const runtime = {
+        device,
+        errorRegistry: { fire: (error: unknown) => errors.push(error) },
+      } as unknown as RenderSystemRuntime;
+      const layout = device
+        .createBindGroupLayout(createHdrpClusterMembershipBindGroupLayoutDescriptor())
+        .unwrap();
+      const emptyFrame = (grid: { x: number; y: number; z: number }) => {
+        const result = prepareStandardLighting({
+          directional: undefined,
+          local: [],
+          view: mat4.create(),
+          projection: mat4.create(),
+          near: 0.1,
+          far: 100,
+          grid,
+          lightCount: 1,
+          renderPath: 'forward',
+        });
+        expect(result.ok).toBe(true);
+        if (!result.ok) throw result.error;
+        return result.value;
+      };
+      const small = emptyFrame({ x: 2, y: 2, z: 2 });
+      const large = emptyFrame({ x: 4, y: 4, z: 4 });
+      const smallTransport = selectStandardClusterTransport(
+        { compute: true, storageBuffer: true, membershipPipelineReady: true },
+        small,
+      );
+      const largeTransport = selectStandardClusterTransport(
+        { compute: true, storageBuffer: true, membershipPipelineReady: true },
+        large,
+      );
+      expect(smallTransport.ok && largeTransport.ok).toBe(true);
+      if (!smallTransport.ok || !largeTransport.ok) return;
+      const frameState = {
+        hdrpClusterMembership: null,
+        installedPipelineConfig: undefined,
+      } as unknown as RenderFrameState;
+      const internals = {
+        device,
+        errorRegistry: runtime.errorRegistry,
+      } as unknown as RenderSystemInternals;
+      const first = writeHdrpClusterAndSsaoBuffers(
+        internals,
+        frameState,
+        camera(),
+        small,
+        smallTransport.value,
+        undefined,
+        true,
+        layout,
+      );
+      expect(first.ok).toBe(true);
+      const firstMembership = frameState.hdrpClusterMembership;
+      expect(firstMembership).not.toBeNull();
+      if (firstMembership === null) return;
+      const firstGridBuffer = firstMembership.clusterGridBuffer;
+      const second = writeHdrpClusterAndSsaoBuffers(
+        internals,
+        frameState,
+        camera(),
+        large,
+        largeTransport.value,
+        undefined,
+        true,
+        layout,
+      );
+      expect(second.ok).toBe(true);
+      expect(frameState.hdrpClusterMembership).not.toBeNull();
+      expect(frameState.hdrpClusterMembership?.bindGroup).not.toBe(firstMembership.bindGroup);
+      expect(frameState.hdrpClusterMembership?.clusterGridBuffer).not.toBe(firstGridBuffer);
+      expect(errors).toEqual([]);
+    });
+  });
+
+  it('keeps the cached LKG and cleans partial candidate buffers after growth allocation fails', async () => {
+    const adapter = new RhiNullAdapter();
+    const baseResult = await adapter.requestDevice();
+    expect(baseResult.ok).toBe(true);
+    if (!baseResult.ok) return;
+    const base = baseResult.value;
+    let createCalls = 0;
+    let failOnCall = Number.POSITIVE_INFINITY;
+    const candidateBuffers: unknown[] = [];
+    const errors: unknown[] = [];
+    const device = {
+      caps: base.caps,
+      features: base.features,
+      limits: base.limits,
+      queue: base.queue,
+      lost: base.lost,
+      createBuffer: (descriptor: Parameters<typeof base.createBuffer>[0]) => {
+        createCalls += 1;
+        if (createCalls === failOnCall) {
+          return rhiErr(
+            new RhiError({
+              code: 'webgpu-runtime-error',
+              expected: 'candidate buffer allocation succeeds',
+              hint: 'test candidate allocation failure',
+            }),
+          );
+        }
+        const created = base.createBuffer(descriptor);
+        if (created.ok) candidateBuffers.push(created.value);
+        return created;
+      },
+      createBindGroupLayout: (descriptor: Parameters<typeof base.createBindGroupLayout>[0]) =>
+        base.createBindGroupLayout(descriptor),
+      destroyBuffer: (buffer: Parameters<typeof base.destroyBuffer>[0]) =>
+        base.destroyBuffer(buffer),
+    } as unknown as RhiDevice;
+    const runtime = {
+      device,
+      errorRegistry: { fire: (error: unknown) => errors.push(error) },
+    } as unknown as RenderSystemRuntime;
+    const small = getOrCreateHdrpBuffers(runtime, { x: 2, y: 2, z: 2 });
+    expect(small).not.toBeNull();
+    if (small === null) return;
+    const oldCandidateCount = candidateBuffers.length;
+    failOnCall = createCalls + 3;
+    const failed = getOrCreateHdrpBuffers(runtime, { x: 8, y: 8, z: 8 });
+    expect(failed).toBeNull();
+    expect(candidateBuffers.length).toBe(oldCandidateCount + 2);
+    const ledger = base as unknown as {
+      readonly bookkeeper: { isDestroyed(handle: unknown): boolean };
+    };
+    expect(ledger.bookkeeper.isDestroyed(candidateBuffers[oldCandidateCount])).toBe(true);
+    expect(ledger.bookkeeper.isDestroyed(candidateBuffers[oldCandidateCount + 1])).toBe(true);
+    expect(ledger.bookkeeper.isDestroyed(small.lightDataBuffer)).toBe(false);
+    expect(getOrCreateHdrpBuffers(runtime, { x: 2, y: 2, z: 2 })).toBe(small);
+    expect(errors).toHaveLength(1);
+  });
+});

package/src/__tests__/standard-lighting.integration.test.ts

@@ -0,0 +1,67 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import {
+  prepareStandardLighting,
+  type StandardLightFrame,
+} from '../pipeline/standard-lighting/prepare';
+
+function makeFrame(lightCount: 1 | 32 | 256, localCount: number): StandardLightFrame {
+  const local = Array.from({ length: localCount }, (_, index) => ({
+    kind: index % 2 === 0 ? ('point' as const) : ('spot' as const),
+    shadowed: false,
+    position: vec3.create((index % 4) - 1.5, 0, -4 - (index % 8)),
+    range: 2,
+  }));
+  return {
+    directional: {
+      kind: 'directional',
+      direction: vec3.create(0, -1, 0),
+      color: vec3.create(1, 1, 1),
+      intensity: 2,
+    },
+    local,
+    view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+    projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+    near: 0.1,
+    far: 100,
+    grid: { x: 4, y: 3, z: 4 },
+    lightCount,
+    renderPath: 'forward',
+  };
+}
+
+describe('Standard shared lighting derivation', () => {
+  it.each([
+    [1, 1],
+    [32, 32],
+    [256, 256],
+  ] as const)('accepts the %i local-light budget without truncation', (lightCount, localCount) => {
+    const result = prepareStandardLighting(makeFrame(lightCount, localCount));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.local.length).toBe(localCount);
+    expect(result.value.membershipLightCount).toBe(localCount);
+  });
+
+  it('keeps DirectionalLight global and out of cluster membership', () => {
+    const result = prepareStandardLighting(makeFrame(1, 1));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.directional?.kind).toBe('directional');
+    expect(result.value.membershipLightCount).toBe(1);
+    expect(
+      Array.from(result.value.lightIndexList.slice(0, result.value.membershipEntryCount)),
+    ).not.toContain(1);
+  });
+
+  it('rejects local lights above the 256-light budget without truncation', () => {
+    const result = prepareStandardLighting(makeFrame(256, 257));
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    if (result.error.code !== 'standard-light-budget-exceeded') return;
+    expect(result.error.detail).toEqual({ actual: 257, budget: 256 });
+  });
+});