@forgeax/engine-render 0.1.4 → 0.1.6

package/src/__tests__/scene-temporal-coverage.unit.test.ts

@@ -1,259 +0,0 @@
-import { vec3 } from '@forgeax/engine-math';
-import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
-import type { Buffer } from '@forgeax/engine-rhi';
-import { RhiNullCommandEncoder, RhiNullDevice, RhiNullQueue } from '@forgeax/engine-rhi-null';
-import { RenderQueue } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
-import type { RenderFeatureGraphContribution } from '../features/graph-contribution';
-import {
-  createSceneTemporalDepthTarget,
-  createSceneTemporalTarget,
-  SCENE_TEMPORAL_CLEAR_VALUE,
-  SCENE_TEMPORAL_PACKED_ABI,
-  sceneTemporalCoverage,
-} from '../features/scene-temporal';
-import { createRenderFeatureTarget } from '../features/targets';
-import type { RenderPipelineFrame } from '../render-pipeline';
-import type {
-  DispatchEntry,
-  RenderableSnapshot,
-  RenderableTemporalSnapshot,
-} from '../render-system-extract';
-
-function matrix(x = 0): Float32Array {
-  const value = new Float32Array(16);
-  value[0] = 1;
-  value[5] = 1;
-  value[10] = 1;
-  value[15] = 1;
-  value[12] = x;
-  return value;
-}
-
-function temporal(overrides: Partial<RenderableTemporalSnapshot> = {}): RenderableTemporalSnapshot {
-  return {
-    previousEpoch: 1,
-    previousSource: 'last-submitted',
-    reactive: false,
-    reactiveReasons: [],
-    previousTransform: { world: matrix() },
-    previousInstances: undefined,
-    previousSkin: undefined,
-    previousMorphWeights: undefined,
-    ...overrides,
-  };
-}
-
-function renderable(
-  entityKey: number,
-  overrides: Partial<RenderableSnapshot> = {},
-): RenderableSnapshot {
-  const material = {
-    baseColor: vec3.create(1, 1, 1),
-    metallic: 0,
-    roughness: 1,
-    materialHandle: entityKey,
-  };
-  return {
-    assetHandle: 1,
-    transform: { world: matrix() },
-    material,
-    materials: [material],
-    materialBindingSources: ['engine-default'],
-    worldId: 0,
-    entityKey,
-    temporal: temporal(),
-    ...overrides,
-  };
-}
-
-function dispatch(renderableIndex: number, overrides: Partial<DispatchEntry> = {}): DispatchEntry {
-  return {
-    entityIndex: renderableIndex,
-    materialHandle: renderableIndex + 1,
-    renderableIndex,
-    passIndex: 0,
-    queue: RenderQueue.Geometry,
-    layer: 0,
-    tags: {},
-    renderState: undefined,
-    defines: undefined,
-    vertexEntry: undefined,
-    fragmentEntry: undefined,
-    materialShaderId: 'forgeax::standard-pbr',
-    paramSnapshot: undefined,
-    ...overrides,
-  };
-}
-
-function feature(
-  temporalCoverage: 'exact' | 'reactive' | undefined,
-  writesTemporal: boolean,
-  identity = 'forgeax::vfx',
-): RenderFeatureGraphContribution {
-  const color = createRenderFeatureTarget({
-    kind: 'scene-color',
-    format: 'rgba16float',
-    sampleCount: 1,
-  });
-  const temporalTarget = createRenderFeatureTarget({
-    kind: 'scene-temporal',
-    format: 'rgba16float',
-    sampleCount: 1,
-  });
-  return {
-    featureIdentity: identity,
-    order: 1,
-    resources: [],
-    topologySignature: 'vfx',
-    passes: [
-      {
-        featureIdentity: identity,
-        order: 1,
-        name: `${identity}::draw`,
-        descriptor: { reads: [], writes: [] },
-        dependsOn: [],
-        graphics: {
-          attachments: {
-            colors: [
-              { resource: color, format: 'rgba16float', loadOp: 'load', storeOp: 'store' },
-              ...(writesTemporal
-                ? [
-                    {
-                      resource: temporalTarget,
-                      format: 'rgba16float',
-                      loadOp: 'load' as const,
-                      storeOp: 'store' as const,
-                    },
-                  ]
-                : []),
-            ],
-          },
-          ...(temporalCoverage === undefined ? {} : { temporalCoverage }),
-          draws: [{} as never],
-        },
-      },
-    ],
-  };
-}
-
-describe('scene temporal target and coverage', () => {
-  it('allocates one single-sample rgba16float target with the packed clear ABI', () => {
-    const device = new RhiNullDevice(
-      new RhiNullQueue(),
-      (bookkeeper, owner) => new RhiNullCommandEncoder(bookkeeper, owner),
-    );
-    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
-    const target = createSceneTemporalTarget(graph).unwrap();
-    const compiled = graph.compile({ device, surfaceSize: { width: 8, height: 8 } }).unwrap();
-
-    expect(target).toMatchObject({ format: 'rgba16float', sampleCount: 1 });
-    expect(SCENE_TEMPORAL_PACKED_ABI).toMatchObject({
-      x: expect.any(String),
-      w: 'reactive-0-to-1',
-    });
-    expect(SCENE_TEMPORAL_CLEAR_VALUE).toEqual({ r: 0, g: 0, b: -1, a: 1 });
-    expect(compiled.inspect()).toMatchObject({
-      passes: [expect.objectContaining({ name: 'scene-temporal-clear', kind: 'raster' })],
-      resources: [expect.objectContaining({ label: 'scene-temporal', origin: 'created' })],
-    });
-  });
-
-  it('allocates an independent depth authority for unjittered temporal replay', () => {
-    const device = new RhiNullDevice(
-      new RhiNullQueue(),
-      (bookkeeper, owner) => new RhiNullCommandEncoder(bookkeeper, owner),
-    );
-    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
-    const depth = createSceneTemporalDepthTarget(graph).unwrap();
-    const compiled = graph.compile({ device, surfaceSize: { width: 8, height: 8 } }).unwrap();
-
-    expect(depth).toMatchObject({ format: 'depth24plus-stencil8', sampleCount: 1 });
-    expect(compiled.inspect().resources).toEqual([
-      expect.objectContaining({ label: 'scene-temporal-depth', origin: 'created' }),
-    ]);
-  });
-
-  it('classifies rigid, instances, skinning, morph, and alpha-cutout as exact', () => {
-    const skinMatrices = matrix();
-    const skin = {
-      jointCount: 1,
-      jointMatrices: skinMatrices,
-      byteOffset: 0,
-      buffer: {} as Buffer,
-    };
-    const renderables = [
-      renderable(1),
-      renderable(2, {
-        instances: { transforms: matrix(2), instanceCount: 1, cacheKey: 2, archVersion: 1 },
-        temporal: temporal({
-          previousInstances: {
-            transforms: matrix(1),
-            instanceCount: 1,
-            cacheKey: 2,
-            archVersion: 1,
-          },
-        }),
-      }),
-      renderable(3, { skin, temporal: temporal({ previousSkin: skin }) }),
-      renderable(4, {
-        morphWeights: new Float32Array([0.75]),
-        temporal: temporal({ previousMorphWeights: new Float32Array([0.25]) }),
-      }),
-      renderable(5),
-    ];
-    const summary = sceneTemporalCoverage({
-      renderables,
-      dispatch: renderables.map((_, index) =>
-        dispatch(
-          index,
-          index === 4 ? { queue: RenderQueue.AlphaTest, paramSnapshot: { alphaCutoff: 0.5 } } : {},
-        ),
-      ),
-      features: [],
-    });
-
-    expect(summary).toMatchObject({ complete: true, exact: 5, reactive: 0, missing: 0 });
-    expect(summary.contributors.map((contributor) => contributor.lane)).toEqual([
-      'rigid',
-      'instances',
-      'skinning',
-      'morph',
-      'alpha-cutout',
-    ]);
-  });
-
-  it('keeps conservative producers reactive and fails closed for undeclared coverage', () => {
-    const renderables = [
-      renderable(1),
-      renderable(2, {
-        material: { ...renderable(2).material, materialShaderId: 'forgeax::sprite' },
-      }),
-      renderable(3),
-    ];
-    const summary = sceneTemporalCoverage({
-      renderables,
-      dispatch: [
-        dispatch(0, { queue: RenderQueue.Transparent }),
-        dispatch(1, { materialShaderId: 'forgeax::sprite' }),
-        dispatch(2, { materialShaderId: 'custom::wind', vertexEntry: 'vs_wind' }),
-      ],
-      features: [
-        feature('reactive', false, 'forgeax::vfx'),
-        feature(undefined, false, 'forgeax::grid'),
-      ],
-    });
-
-    expect(summary).toMatchObject({ complete: false, exact: 0, reactive: 4, missing: 1 });
-    expect(summary.missingContributors).toEqual(['feature:forgeax::grid:forgeax::grid::draw']);
-  });
-
-  it('requires exact RenderFeatures to write scene-temporal', () => {
-    expect(
-      sceneTemporalCoverage({ renderables: [], dispatch: [], features: [feature('exact', false)] }),
-    ).toMatchObject({ complete: false, missing: 1 });
-    expect(
-      sceneTemporalCoverage({ renderables: [], dispatch: [], features: [feature('exact', true)] }),
-    ).toMatchObject({ complete: true, exact: 1 });
-  });
-});

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

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

@@ -1,42 +0,0 @@
-/// <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__/taa-history-store.unit.test.ts

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