@forgeax/engine-render 0.1.2

package/src/__tests__/ssao-kernel-surface.unit.test.ts

@@ -0,0 +1,15 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { SSAO_KERNEL_SAMPLE_COUNT } from '../ssao-data';
+
+const ownerSource = readFileSync(new URL('../ssao-data.ts', import.meta.url), 'utf8');
+const bufferSource = readFileSync(new URL('../ssao-buffers.ts', import.meta.url), 'utf8');
+
+describe('SSAO kernel cardinality owner', () => {
+  it('keeps the generated and uploaded sample count on one owner', () => {
+    expect(SSAO_KERNEL_SAMPLE_COUNT).toBe(64);
+    expect(ownerSource.match(/export const SSAO_KERNEL_SAMPLE_COUNT\s*=\s*64/g)).toHaveLength(1);
+    expect(bufferSource).toContain('SSAO_KERNEL_SAMPLE_COUNT');
+    expect(bufferSource).not.toMatch(/const (KERNEL_SIZE|KERNEL_SAMPLE_COUNT)\s*=\s*64/);
+  });
+});

package/src/__tests__/sun-snapshot-consumers.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { createEnvironmentConsumerSnapshot } from '../record/frame-lighting';
+
+describe('analytic environment consumer snapshot', () => {
+  it('gives IBL, direct BRDF, CSM, background, and disc one Sun generation', () => {
+    const snapshot = createEnvironmentConsumerSnapshot({
+      generation: 4,
+      signature: 'environment-4',
+      direction: [0, 0.8, -0.6],
+      color: [1, 0.9, 0.8],
+      illuminance: 12,
+    });
+    expect(new Set(snapshot.consumers.map((consumer) => consumer.generation))).toEqual(
+      new Set([4]),
+    );
+    expect(snapshot.ibl.includesSunDisc).toBe(false);
+    expect(snapshot.background.includesSunDisc).toBe(true);
+    expect(snapshot.sunDisc.illuminance).toBe(12);
+    expect(snapshot.direct.illuminance).toBe(12);
+  });
+
+  it('does not add a second Sun contribution for mirror or metal consumers', () => {
+    const snapshot = createEnvironmentConsumerSnapshot({
+      generation: 5,
+      signature: 'environment-5',
+      direction: [0, 1, 0],
+      color: [1, 1, 1],
+      illuminance: 20,
+    });
+    expect(snapshot.ibl.sunContribution).toBe(0);
+    expect(snapshot.direct.secondarySunContribution).toBe(0);
+    expect(snapshot.materials.mirrorSunCount).toBe(1);
+    expect(snapshot.materials.metalSunCount).toBe(1);
+  });
+});

package/src/__tests__/surface-backend-kind-owner.test-d.ts

@@ -0,0 +1,42 @@
+/// <reference types="node" />
+
+import { readFileSync } from 'node:fs';
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { SurfaceBackendKind, SwapChainFormatPair } from '../surface-format';
+import { resolveSurfaceFormatPair } from '../surface-format';
+
+type BackendKindOwner = RhiDevice['caps']['backendKind'];
+type ResolverBackendKind = Parameters<typeof resolveSurfaceFormatPair>[0];
+const surfaceSource = readFileSync(new URL('../surface-format.ts', import.meta.url), 'utf8');
+
+describe('surface backend kind owner', () => {
+  it('keeps exact membership bilateral across the RHI owner and render projections', () => {
+    expectTypeOf<BackendKindOwner>().toEqualTypeOf<
+      'webgpu' | 'wgpu-native' | 'wgpu-webgl2' | 'null'
+    >();
+    expectTypeOf<SurfaceBackendKind>().toEqualTypeOf<BackendKindOwner>();
+    expectTypeOf<BackendKindOwner>().toEqualTypeOf<SurfaceBackendKind>();
+    expectTypeOf<ResolverBackendKind>().toEqualTypeOf<BackendKindOwner>();
+    expectTypeOf<BackendKindOwner>().toEqualTypeOf<ResolverBackendKind>();
+
+    const resolve = (kind: SurfaceBackendKind): SwapChainFormatPair =>
+      resolveSurfaceFormatPair(kind, 'rgba8unorm', 'rgba8unorm-srgb');
+    resolve('webgpu');
+    resolve('wgpu-native');
+    resolve('wgpu-webgl2');
+    resolve('null');
+    // @ts-expect-error unknown backend kinds remain outside the closed owner union.
+    resolve('backend-kind-not-real');
+  });
+
+  it('keeps the render vocabulary derived from the RHI capability authority', () => {
+    expect(surfaceSource).toContain("import type { RhiDevice } from '@forgeax/engine-rhi';");
+    expect(surfaceSource).toContain(
+      "export type SurfaceBackendKind = RhiDevice['caps']['backendKind'];",
+    );
+    expect(surfaceSource).not.toContain(
+      "export type SurfaceBackendKind = 'webgpu' | 'wgpu-native' | 'wgpu-webgl2' | 'null';",
+    );
+  });
+});

package/src/__tests__/surface-configuration.unit.test.ts

@@ -0,0 +1,92 @@
+import type { RhiCanvasContext, RhiDevice } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import { describe, expect, it, vi } from 'vitest';
+import { configureSurface } from '../render-system';
+import { resolveSurfaceFormatPair } from '../surface-format';
+
+function device(backendKind: 'webgpu' | 'wgpu-webgl2', storageBuffer = false): RhiDevice {
+  return {
+    limits: { maxStorageBuffersPerShaderStage: 0 },
+    caps: { backendKind, storageBuffer },
+  } as unknown as RhiDevice;
+}
+
+describe('configureSurface', () => {
+  it('projects the configured surface format into graph topology without reinterpretation drift', () => {
+    expect(resolveSurfaceFormatPair('webgpu', 'bgra8unorm', 'bgra8unorm-srgb')).toEqual({
+      storage: 'bgra8unorm',
+      view: 'bgra8unorm-srgb',
+    });
+    expect(resolveSurfaceFormatPair('wgpu-webgl2', 'rgba8unorm', 'rgba8unorm-srgb')).toEqual({
+      storage: 'rgba8unorm-srgb',
+      view: 'rgba8unorm-srgb',
+    });
+  });
+
+  it('keeps native WebGPU sRGB view support when texture binding is available', () => {
+    const configure = vi.fn(() => ok(undefined));
+    const context = { configure } as unknown as RhiCanvasContext;
+    const webGpuDevice = device('webgpu', true);
+    const result = configureSurface(context, webGpuDevice, 'bgra8unorm', 'bgra8unorm-srgb');
+    expect(result.ok).toBe(true);
+    expect(configure).toHaveBeenCalledWith({
+      device: webGpuDevice,
+      format: 'bgra8unorm',
+      alphaMode: 'premultiplied',
+      usage: 0x10 | 0x04 | 0x01,
+      viewFormats: ['bgra8unorm-srgb'],
+    });
+  });
+
+  it('keeps COPY_SRC on a low-capability WebGPU surface', () => {
+    const configure = vi.fn(() => ok(undefined));
+    const context = { configure } as unknown as RhiCanvasContext;
+    const webGpuDevice = device('webgpu');
+    const result = configureSurface(context, webGpuDevice, 'bgra8unorm', 'bgra8unorm-srgb');
+    expect(result.ok).toBe(true);
+    expect(configure).toHaveBeenCalledWith({
+      device: webGpuDevice,
+      format: 'bgra8unorm',
+      alphaMode: 'premultiplied',
+      usage: 0x10 | 0x01,
+      viewFormats: ['bgra8unorm-srgb'],
+    });
+  });
+
+  it('keeps the wgpu WebGL2 surface COLOR_TARGET-only', () => {
+    const configure = vi.fn(() => ok(undefined));
+    const context = { configure } as unknown as RhiCanvasContext;
+    const webGlDevice = device('wgpu-webgl2');
+    const result = configureSurface(context, webGlDevice, 'rgba8unorm', 'rgba8unorm-srgb');
+    expect(result.ok).toBe(true);
+    expect(configure).toHaveBeenCalledWith({
+      device: webGlDevice,
+      format: 'rgba8unorm-srgb',
+      alphaMode: 'opaque',
+      usage: 0x10,
+    });
+    const descriptor = (configure.mock.calls[0] as unknown as [Record<string, unknown>])[0];
+    expect(descriptor).not.toHaveProperty('viewFormats');
+  });
+
+  it('uses the capability gate when WebGL2 reports a translated storage limit', () => {
+    const configure = vi.fn(() => ok(undefined));
+    const context = { configure } as unknown as RhiCanvasContext;
+    const webGlDevice = {
+      limits: { maxStorageBuffersPerShaderStage: 8 },
+      caps: { backendKind: 'wgpu-webgl2', storageBuffer: false },
+    } as unknown as RhiDevice;
+
+    const result = configureSurface(context, webGlDevice, 'rgba8unorm', 'rgba8unorm-srgb');
+
+    expect(result.ok).toBe(true);
+    expect(configure).toHaveBeenCalledWith({
+      device: webGlDevice,
+      format: 'rgba8unorm-srgb',
+      alphaMode: 'opaque',
+      usage: 0x10,
+    });
+    const descriptor = (configure.mock.calls[0] as unknown as [Record<string, unknown>])[0];
+    expect(descriptor).not.toHaveProperty('viewFormats');
+  });
+});

package/src/__tests__/taa-history-store.unit.test.ts

@@ -0,0 +1,196 @@
+import { type CompiledRenderGraph, RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiError, Texture, TextureDescriptor } from '@forgeax/engine-rhi';
+import { RhiNullCommandEncoder, RhiNullDevice, RhiNullQueue } from '@forgeax/engine-rhi-null';
+import { ok, type Result } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import type { RenderPipelineFrame } from '../render-pipeline';
+import { type TaaHistoryPreparation, TaaHistoryStore } from '../taa-history-store';
+
+class HistoryDevice extends RhiNullDevice {
+  readonly textureDescriptors: TextureDescriptor[] = [];
+  readonly destroyedTextures: Texture[] = [];
+
+  override createTexture(descriptor: TextureDescriptor): Result<Texture, RhiError> {
+    this.textureDescriptors.push(descriptor);
+    return super.createTexture(descriptor);
+  }
+
+  override destroyTexture(texture: Texture): Result<void, RhiError> {
+    this.destroyedTextures.push(texture);
+    return super.destroyTexture(texture);
+  }
+}
+
+function device(): HistoryDevice {
+  return new HistoryDevice(
+    new RhiNullQueue(),
+    (bookkeeper, owner) => new RhiNullCommandEncoder(bookkeeper, owner),
+  );
+}
+
+function input(overrides: Partial<Parameters<TaaHistoryStore['prepare']>[0]> = {}) {
+  return {
+    enabled: true,
+    width: 16,
+    height: 8,
+    viewId: '0:1:0',
+    pipelineOwnerGeneration: 1,
+    surfaceFormat: 'bgra8unorm' as const,
+    ...overrides,
+  };
+}
+
+function graphWithRetirement(retirement: Promise<Result<void, never>>) {
+  return {
+    retire: () => retirement,
+  } as unknown as CompiledRenderGraph<RenderPipelineFrame>;
+}
+
+function commit(
+  store: TaaHistoryStore,
+  preparation: TaaHistoryPreparation,
+  retirement: Promise<Result<void, never>> = Promise.resolve(ok(undefined)),
+) {
+  const graph = graphWithRetirement(retirement);
+  store.commitGraph(graph, preparation);
+  return graph;
+}
+
+describe('TaaHistoryStore', () => {
+  it('allocates no history while TAA is disabled', () => {
+    const historyDevice = device();
+    const store = new TaaHistoryStore(historyDevice);
+    commit(store, store.prepare(input({ enabled: false })).unwrap());
+
+    expect(historyDevice.textureDescriptors).toEqual([]);
+    expect(store.inspect()).toMatchObject({
+      enabled: false,
+      ownerGeneration: 0,
+      historyBytes: 0,
+      valid: false,
+    });
+  });
+
+  it('imports four packed rgba16float textures and reuses one owner generation', () => {
+    const historyDevice = device();
+    const store = new TaaHistoryStore(historyDevice);
+    const prepared = store.prepare(input()).unwrap();
+    const builder = new RenderGraphBuilder<RenderPipelineFrame>();
+    const imported = prepared.importResources(builder).unwrap();
+    expect(imported).toMatchObject({
+      colorRead: expect.any(Object),
+      colorWrite: expect.any(Object),
+      temporalRead: expect.any(Object),
+      temporalWrite: expect.any(Object),
+    });
+    const compiled = builder
+      .compile({ device: historyDevice, surfaceSize: { width: 16, height: 8 } })
+      .unwrap();
+    store.commitGraph(compiled, prepared);
+
+    expect(historyDevice.textureDescriptors).toHaveLength(4);
+    expect(historyDevice.textureDescriptors).toEqual(
+      expect.arrayContaining([expect.objectContaining({ format: 'rgba16float', sampleCount: 1 })]),
+    );
+    expect(compiled.inspect().resources).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ label: 'taa-history-color-read', origin: 'imported' }),
+        expect.objectContaining({ label: 'taa-history-color-write', origin: 'imported' }),
+        expect.objectContaining({ label: 'taa-history-temporal-read', origin: 'imported' }),
+        expect.objectContaining({ label: 'taa-history-temporal-write', origin: 'imported' }),
+      ]),
+    );
+    expect(store.inspect()).toMatchObject({
+      enabled: true,
+      ownerGeneration: 1,
+      format: 'rgba16float',
+      historyBytes: 32 * 16 * 8,
+    });
+
+    const reused = store.prepare(input()).unwrap();
+    expect(reused.ownerGeneration).toBe(1);
+    expect(historyDevice.textureDescriptors).toHaveLength(4);
+    store.abort(reused);
+  });
+
+  it('keeps the last-known-good generation when candidate graph construction aborts', () => {
+    const historyDevice = device();
+    const store = new TaaHistoryStore(historyDevice);
+    commit(store, store.prepare(input()).unwrap());
+    const candidate = store.prepare(input({ width: 32 })).unwrap();
+
+    store.abort(candidate);
+
+    expect(historyDevice.textureDescriptors).toHaveLength(8);
+    expect(historyDevice.destroyedTextures).toHaveLength(4);
+    expect(store.inspect()).toMatchObject({ ownerGeneration: 1, width: 16, historyBytes: 4096 });
+  });
+
+  it('retires replaced generations only after the compiled graph retirement fence', async () => {
+    const historyDevice = device();
+    const store = new TaaHistoryStore(historyDevice);
+    let releaseRetirement: ((result: Result<void, never>) => void) | undefined;
+    const retirement = new Promise<Result<void, never>>((resolve) => {
+      releaseRetirement = resolve;
+    });
+    const oldGraph = commit(store, store.prepare(input()).unwrap(), retirement);
+    commit(store, store.prepare(input({ width: 32 })).unwrap());
+
+    const retiring = store.retireGraph(oldGraph);
+    expect(store.inspect()).toMatchObject({ ownerGeneration: 2, retiringGenerations: 1 });
+    expect(historyDevice.destroyedTextures).toHaveLength(0);
+
+    releaseRetirement?.(ok(undefined));
+    await retiring;
+    await Promise.resolve();
+    expect(historyDevice.destroyedTextures).toHaveLength(4);
+    expect(store.inspect().retiringGenerations).toBe(0);
+  });
+
+  it('commits direction and validity atomically and invalidates incomplete coverage', () => {
+    const historyDevice = device();
+    const store = new TaaHistoryStore(historyDevice);
+    commit(store, store.prepare(input()).unwrap());
+    const view = {
+      historyValid: false,
+      resetReason: 'first-frame' as const,
+    } as Parameters<TaaHistoryStore['beginFrame']>[0];
+
+    const aborted = store.beginFrame(view);
+    aborted.abort();
+    expect(store.inspect()).toMatchObject({ direction: 'a-to-b', valid: false });
+
+    store.beginFrame(view).commit();
+    expect(store.inspect()).toMatchObject({ direction: 'b-to-a', valid: true });
+
+    const nextView = { ...view, historyValid: true } as NonNullable<
+      Parameters<TaaHistoryStore['beginFrame']>[0]
+    >;
+    const incomplete = store.beginFrame(nextView, false);
+    expect(incomplete.valid).toBe(false);
+    incomplete.commit();
+    expect(store.inspect()).toMatchObject({
+      direction: 'a-to-b',
+      valid: false,
+      resetReason: 'coverage-incomplete',
+    });
+  });
+
+  it('keeps an explicit invalidation authoritative over a coincident view reset', () => {
+    const historyDevice = device();
+    const store = new TaaHistoryStore(historyDevice);
+    commit(store, store.prepare(input()).unwrap());
+    store.invalidate('world-detached');
+    commit(store, store.prepare(input()).unwrap());
+
+    const attempt = store.beginFrame({
+      historyValid: false,
+      resetReason: 'camera-switch',
+    } as Parameters<TaaHistoryStore['beginFrame']>[0]);
+
+    expect(attempt).toMatchObject({
+      valid: false,
+      resetReason: 'world-detached',
+    });
+  });
+});