@forgeax/engine-render 0.1.7 → 0.1.20

package/src/temporal/temporal-view.ts

@@ -0,0 +1,169 @@
+import { mat4 } from '@forgeax/engine-math';
+import type { CameraProjection } from '../components/camera';
+import type { CameraSnapshot } from '../render-contract';
+
+export const TEMPORAL_JITTER_SAMPLE_COUNT = 8;
+
+export type TemporalViewResetReason =
+  | 'first-frame'
+  | 'camera-switch'
+  | 'history-version-changed'
+  | 'projection-kind-changed'
+  | 'projection-range-changed';
+
+export interface SubmittedTemporalView {
+  readonly viewId: string;
+  readonly historyVersion: number;
+  readonly projection: CameraProjection;
+  readonly near: number;
+  readonly far: number;
+  readonly jitterUv: readonly [number, number];
+  readonly unjitteredViewProjection: Float32Array;
+}
+
+export interface TemporalView {
+  readonly viewId: string;
+  readonly historyVersion: number;
+  readonly temporalFrameIndex: number;
+  readonly historyValid: boolean;
+  readonly resetReason: TemporalViewResetReason | undefined;
+  readonly currentJitterUv: readonly [number, number];
+  readonly previousJitterUv: readonly [number, number];
+  readonly currentJitteredViewProjection: Float32Array;
+  readonly currentUnjitteredViewProjection: Float32Array;
+  readonly previousUnjitteredViewProjection: Float32Array;
+  readonly projection: CameraProjection;
+  readonly near: number;
+  readonly far: number;
+}
+
+export interface TemporalViewInput {
+  readonly camera: CameraSnapshot;
+  readonly temporalFrameIndex: number;
+  readonly surfaceWidth: number;
+  readonly surfaceHeight: number;
+  readonly lastSubmitted?: SubmittedTemporalView;
+}
+
+export function temporalViewId(worldId: number, entityKey: number): string {
+  const raw = entityKey >>> 0;
+  const index = raw & 0x00ffffff;
+  const generation = (raw >>> 24) & 0xff;
+  return `${worldId}:${index}:${generation}`;
+}
+
+function halton(index: number, base: number): number {
+  let result = 0;
+  let fraction = 1 / base;
+  let value = index;
+  while (value > 0) {
+    result += fraction * (value % base);
+    value = Math.floor(value / base);
+    fraction /= base;
+  }
+  return result;
+}
+
+export function temporalJitterSample(temporalFrameIndex: number): readonly [number, number] {
+  const sampleIndex =
+    ((Math.trunc(temporalFrameIndex) % TEMPORAL_JITTER_SAMPLE_COUNT) +
+      TEMPORAL_JITTER_SAMPLE_COUNT) %
+    TEMPORAL_JITTER_SAMPLE_COUNT;
+  const haltonIndex = sampleIndex + 1;
+  return [halton(haltonIndex, 2) - 0.5, halton(haltonIndex, 3) - 0.5];
+}
+
+function temporalJitterUv(
+  temporalFrameIndex: number,
+  surfaceWidth: number,
+  surfaceHeight: number,
+): readonly [number, number] {
+  const sample = temporalJitterSample(temporalFrameIndex);
+  return [sample[0] / Math.max(1, surfaceWidth), sample[1] / Math.max(1, surfaceHeight)];
+}
+
+function cameraProjection(camera: CameraSnapshot): Float32Array {
+  const projection = mat4.create();
+  if (camera.projection === 'orthographic') {
+    mat4.orthographic(
+      projection,
+      camera.orthoLeft,
+      camera.orthoRight,
+      camera.orthoBottom,
+      camera.orthoTop,
+      camera.near,
+      camera.far,
+    );
+  } else {
+    mat4.perspective(projection, camera.fov, camera.aspect, camera.near, camera.far);
+  }
+  return projection;
+}
+
+function resetReason(
+  current: CameraSnapshot,
+  viewId: string,
+  previous: SubmittedTemporalView | undefined,
+): TemporalViewResetReason | undefined {
+  if (previous === undefined) return 'first-frame';
+  if (previous.viewId !== viewId) return 'camera-switch';
+  if (previous.historyVersion !== (current.historyVersion ?? 0)) {
+    return 'history-version-changed';
+  }
+  if (previous.projection !== current.projection) return 'projection-kind-changed';
+  if (!Object.is(previous.near, current.near) || !Object.is(previous.far, current.far)) {
+    return 'projection-range-changed';
+  }
+  return undefined;
+}
+
+export function projectTemporalView(input: TemporalViewInput): TemporalView {
+  const { camera } = input;
+  const viewId = temporalViewId(camera.worldId ?? 0, camera.entityKey ?? 0);
+  const currentJitterUv = temporalJitterUv(
+    input.temporalFrameIndex,
+    input.surfaceWidth,
+    input.surfaceHeight,
+  );
+  const view = mat4.invert(mat4.create(), camera.world);
+  const projection = cameraProjection(camera);
+  const currentUnjitteredViewProjection = mat4.multiply(mat4.create(), projection, view);
+  const clipJitter = mat4.identity(mat4.create());
+  clipJitter[12] = currentJitterUv[0] * 2;
+  clipJitter[13] = currentJitterUv[1] * -2;
+  const jitteredProjection = mat4.multiply(mat4.create(), clipJitter, projection);
+  const currentJitteredViewProjection = mat4.multiply(mat4.create(), jitteredProjection, view);
+  const reason = resetReason(camera, viewId, input.lastSubmitted);
+  const historyValid = reason === undefined;
+  return {
+    viewId,
+    historyVersion: camera.historyVersion ?? 0,
+    temporalFrameIndex: input.temporalFrameIndex,
+    historyValid,
+    resetReason: reason,
+    currentJitterUv,
+    previousJitterUv: historyValid
+      ? (input.lastSubmitted?.jitterUv ?? currentJitterUv)
+      : currentJitterUv,
+    currentJitteredViewProjection,
+    currentUnjitteredViewProjection,
+    previousUnjitteredViewProjection: historyValid
+      ? (input.lastSubmitted?.unjitteredViewProjection ?? currentUnjitteredViewProjection)
+      : currentUnjitteredViewProjection,
+    projection: camera.projection,
+    near: camera.near,
+    far: camera.far,
+  };
+}
+
+export function snapshotSubmittedTemporalView(view: TemporalView): SubmittedTemporalView {
+  return {
+    viewId: view.viewId,
+    historyVersion: view.historyVersion,
+    projection: view.projection,
+    near: view.near,
+    far: view.far,
+    jitterUv: [view.currentJitterUv[0], view.currentJitterUv[1]],
+    unjitteredViewProjection: new Float32Array(view.currentUnjitteredViewProjection),
+  };
+}

package/src/temporal/transaction.ts

@@ -0,0 +1,17 @@
+import {
+  type RendererFrameTransaction,
+  stageRendererFrame,
+} from '../assembly/renderer-frame-transaction';
+import type { TemporalHistory } from './history';
+import type { TemporalView } from './view';
+
+export interface TemporalFrameCandidate {
+  readonly view: TemporalView;
+  readonly history: TemporalHistory;
+}
+
+export function stageTemporalFrame(
+  candidate: TemporalFrameCandidate,
+): RendererFrameTransaction<TemporalFrameCandidate> {
+  return stageRendererFrame(candidate, () => candidate.history.abort());
+}

package/src/temporal/view.ts

@@ -0,0 +1,161 @@
+import type { Antialias } from '../components/camera';
+
+type Jitter = readonly [number, number];
+
+export const HALTON_23_8 = Object.freeze([
+  Object.freeze([0, -1 / 6]),
+  Object.freeze([-1 / 4, 1 / 6]),
+  Object.freeze([1 / 4, -5 / 18]),
+  Object.freeze([-3 / 8, -1 / 18]),
+  Object.freeze([1 / 8, 5 / 18]),
+  Object.freeze([-1 / 8, -7 / 54]),
+  Object.freeze([3 / 8, 11 / 54]),
+  Object.freeze([-7 / 16, 7 / 18]),
+] as const);
+
+export type TemporalResetReason =
+  | 'first-frame'
+  | 'resize'
+  | 'camera-cut'
+  | 'history-version'
+  | 'view-switch'
+  | 'environment-change'
+  | 'fog-change'
+  | 'device-recover'
+  | 'submit-failure';
+
+export interface TemporalViewInput {
+  readonly antialias: Antialias;
+  readonly width: number;
+  readonly height: number;
+  readonly frameIndex?: number;
+  readonly historyVersion?: number;
+  readonly viewIdentity?: string;
+  readonly environmentSignature?: string;
+  readonly fogSignature?: string;
+  readonly deviceGeneration?: number;
+  readonly cameraCut?: boolean;
+  readonly historyValid?: boolean;
+  readonly currentUnjitteredViewProjection?: ArrayLike<number> | undefined;
+  readonly previousUnjitteredViewProjection?: ArrayLike<number> | undefined;
+  readonly resetReason?: TemporalResetReason | undefined;
+}
+
+interface TemporalViewSnapshot {
+  readonly antialias: Antialias;
+  readonly width: number;
+  readonly height: number;
+  readonly frameIndex: number;
+  readonly historyVersion: number;
+  readonly viewIdentity: string;
+  readonly environmentSignature: string;
+  readonly fogSignature: string;
+  readonly deviceGeneration: number;
+  readonly cameraCut: boolean;
+  readonly historyValid: boolean;
+  readonly currentUnjitteredViewProjection: ArrayLike<number> | undefined;
+  readonly previousUnjitteredViewProjection: ArrayLike<number> | undefined;
+  readonly resetReason: TemporalResetReason | undefined;
+}
+
+export interface TemporalView {
+  readonly input: Readonly<TemporalViewSnapshot>;
+  readonly historyVersion: number;
+  readonly mode: 'off' | 'taa';
+  readonly jitter: readonly [number, number] | undefined;
+  readonly jitterCancellationUv: readonly [number, number] | undefined;
+  readonly currentJitterUv: readonly [number, number] | undefined;
+  readonly historyValid: boolean;
+  readonly temporalFrameIndex: number;
+  /** Unjittered matrices are supplied by the renderer projection owner. */
+  readonly currentUnjitteredViewProjection: ArrayLike<number> | undefined;
+  readonly previousUnjitteredViewProjection: ArrayLike<number> | undefined;
+  readonly currentProjection: 'jittered' | 'unjittered';
+  readonly previousProjection: 'unjittered';
+  readonly historyRequired: boolean;
+  readonly resetReason: TemporalResetReason | undefined;
+}
+
+function validDimension(value: number, field: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new RangeError(`${field} must be a positive safe integer.`);
+  }
+  return value;
+}
+
+export function createTemporalView(input: TemporalViewInput): TemporalView {
+  const width = validDimension(input.width, 'width');
+  const height = validDimension(input.height, 'height');
+  const historyVersion = input.historyVersion ?? 0;
+  const frameIndex = input.frameIndex ?? 0;
+  const deviceGeneration = input.deviceGeneration ?? 0;
+  if (!Number.isSafeInteger(historyVersion) || historyVersion < 0) {
+    throw new RangeError('historyVersion must be a non-negative safe integer.');
+  }
+  if (!Number.isSafeInteger(frameIndex) || frameIndex < 0) {
+    throw new RangeError('frameIndex must be a non-negative safe integer.');
+  }
+  if (!Number.isSafeInteger(deviceGeneration) || deviceGeneration < 0) {
+    throw new RangeError('deviceGeneration must be a non-negative safe integer.');
+  }
+  const normalized: TemporalViewSnapshot = Object.freeze({
+    ...input,
+    width,
+    height,
+    frameIndex,
+    historyVersion,
+    viewIdentity: input.viewIdentity ?? 'camera:default',
+    environmentSignature: input.environmentSignature ?? '',
+    fogSignature: input.fogSignature ?? '',
+    deviceGeneration,
+    cameraCut: input.cameraCut ?? false,
+    historyValid: input.historyValid ?? false,
+    currentUnjitteredViewProjection: input.currentUnjitteredViewProjection,
+    previousUnjitteredViewProjection: input.previousUnjitteredViewProjection,
+    resetReason: input.resetReason,
+  });
+  const taa = input.antialias === 'taa';
+  const jitter: Jitter | undefined = taa
+    ? (HALTON_23_8[frameIndex % HALTON_23_8.length] as Jitter)
+    : undefined;
+  return Object.freeze({
+    input: normalized,
+    historyVersion,
+    mode: taa ? 'taa' : 'off',
+    jitter,
+    jitterCancellationUv:
+      jitter === undefined
+        ? undefined
+        : (Object.freeze([jitter[0] / width, jitter[1] / height]) as Jitter),
+    currentJitterUv:
+      jitter === undefined
+        ? undefined
+        : (Object.freeze([jitter[0] / width, jitter[1] / height]) as Jitter),
+    historyValid: normalized.historyValid,
+    temporalFrameIndex: frameIndex,
+    currentUnjitteredViewProjection: input.currentUnjitteredViewProjection,
+    previousUnjitteredViewProjection: input.previousUnjitteredViewProjection,
+    currentProjection: taa ? 'jittered' : 'unjittered',
+    previousProjection: 'unjittered',
+    historyRequired: taa,
+    resetReason: input.resetReason,
+  });
+}
+
+export function resolveTemporalReset(
+  previous: TemporalView | undefined,
+  next: TemporalView,
+): TemporalResetReason | undefined {
+  if (next.mode !== 'taa') return undefined;
+  if (previous === undefined || previous.mode !== 'taa') return 'first-frame';
+  const before = previous.input;
+  const after = next.input;
+  if (before.width !== after.width || before.height !== after.height) return 'resize';
+  if (after.cameraCut) return 'camera-cut';
+  if (before.historyVersion !== after.historyVersion) return 'history-version';
+  if (before.viewIdentity !== after.viewIdentity) return 'view-switch';
+  if (before.environmentSignature !== after.environmentSignature) return 'environment-change';
+  if (before.fogSignature !== after.fogSignature) return 'fog-change';
+  if (before.deviceGeneration !== after.deviceGeneration) return 'device-recover';
+  return undefined;
+}

package/src/transmission/__tests__/capability.unit.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+import {
+  evaluateTransmissionCapability,
+  TransmissionCandidateAdmission,
+  type TransmissionCapabilityFacts,
+} from '../backdrop';
+
+function facts(overrides: Partial<TransmissionCapabilityFacts> = {}): TransmissionCapabilityFacts {
+  return {
+    format: 'rgba16float',
+    renderAttachment: true,
+    copySrc: true,
+    textureBinding: true,
+    mipView: true,
+    filteringSampler: true,
+    bindGroupLayout: true,
+    msaaResolve: true,
+    resourceCreation: true,
+    ...overrides,
+  };
+}
+
+describe('TransmissionBackdrop joint capability verdict', () => {
+  it('requires every real resource and usage fact', () => {
+    const fields = [
+      'format',
+      'renderAttachment',
+      'copySrc',
+      'textureBinding',
+      'mipView',
+      'filteringSampler',
+      'bindGroupLayout',
+      'msaaResolve',
+      'resourceCreation',
+    ] as const;
+
+    for (const field of fields) {
+      const input = field === 'format' ? { format: 'bgra8unorm' } : { [field]: false };
+      const verdict = evaluateTransmissionCapability(facts(input));
+      expect(verdict.ok, field).toBe(false);
+      expect(verdict.missing).toContain(field);
+    }
+  });
+
+  it('does not branch on backend name or a synthetic transmission boolean', () => {
+    const baseline = evaluateTransmissionCapability(facts());
+    const sameFacts = evaluateTransmissionCapability({
+      ...facts(),
+      backendKind: 'wgpu-native',
+    });
+
+    expect(baseline).toEqual(sameFacts);
+    expect(baseline.ok).toBe(true);
+  });
+
+  it('returns a successful receipt only for the complete joint capability', () => {
+    expect(evaluateTransmissionCapability(facts())).toEqual({ ok: true, missing: [] });
+  });
+
+  it('does not publish demand or generation when candidate admission fails', () => {
+    const admission = new TransmissionCandidateAdmission();
+    expect(admission.admit({ activeCount: 1, needsRoughMips: true }, facts())).toMatchObject({
+      ok: true,
+      generation: 1,
+    });
+
+    const rejected = admission.admit(
+      { activeCount: 2, needsRoughMips: true },
+      facts({ copySrc: false }),
+    );
+    expect(rejected).toMatchObject({
+      ok: false,
+      missing: ['copySrc'],
+      published: false,
+      generation: 1,
+      demand: { activeCount: 1, needsRoughMips: true },
+    });
+    expect(admission.inspect()).toEqual({
+      generation: 1,
+      demand: { activeCount: 1, needsRoughMips: true },
+    });
+  });
+});

package/src/transmission/__tests__/composition.integration.test.ts

@@ -0,0 +1,161 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { beforeAll, describe, expect, it } from 'vitest';
+import type { RenderPipelineFrame } from '../../render-pipeline';
+import { createRenderPipelineTarget } from '../../render-pipeline';
+import { sortDispatchByQueue } from '../../render-system-extract';
+import { addTransmissionBackdropPasses, type TransmissionBackdropGraph } from '../backdrop';
+import { fresnelReflectance, resolveRefractionBackdrop } from '../oracle.js';
+
+let device: RhiDevice;
+
+beforeAll(async () => {
+  const adapter = await rhi.requestAdapter();
+  if (!adapter.ok) throw adapter.error;
+  const created = await adapter.value.requestDevice();
+  if (!created.ok) throw created.error;
+  device = created.value;
+});
+
+async function buildComposition(): Promise<{
+  readonly graph: TransmissionBackdropGraph;
+  readonly passes: readonly string[];
+  readonly accesses: ReadonlyMap<string, readonly string[]>;
+  readonly roughMipLevels: readonly number[];
+}> {
+  const roughMipLevels: number[] = [];
+  const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+  const source = createRenderPipelineTarget(graph, 'opaque-resolved', {
+    format: 'rgba16float',
+    size: 'surface',
+    sampleCount: 1,
+  });
+  if (!source.ok) throw source.error;
+  graph
+    .addRasterPass('opaque-resolve', {
+      accesses: [{ resource: source.value.view, usage: 'color-attachment' }],
+      colorAttachments: [{ view: source.value.view, loadOp: 'clear', storeOp: 'store' }],
+      encode: () => undefined,
+    })
+    .unwrap();
+
+  const added = addTransmissionBackdropPasses({
+    graph,
+    source: source.value,
+    demand: { activeCount: 1, needsRoughMips: true },
+    copySize: { width: 8, height: 4 },
+    encodeRoughMip: ({ pass, level }) => {
+      roughMipLevels.push(level);
+      pass.draw(3, 1, 0, 0);
+    },
+  });
+  if (!added.ok) throw added.error;
+  const compiled = graph.compile({ device, surfaceSize: { width: 8, height: 4 } });
+  if (!compiled.ok) throw compiled.error;
+  const encoder = device.createCommandEncoder({ label: 'transmission-composition-test' });
+  if (!encoder.ok) throw encoder.error;
+  const executed = compiled.value.execute({ encoder: encoder.value } as RenderPipelineFrame);
+  if (!executed.ok) throw executed.error;
+  const finished = encoder.value.finish();
+  if (!finished.ok) throw finished.error;
+  const inspected = compiled.value.inspect();
+  return {
+    graph: added.value,
+    passes: inspected.passes.map((pass) => pass.name),
+    accesses: new Map(
+      inspected.passes.map((pass) => [
+        pass.name,
+        pass.accesses.map((access) => `${access.resource}:${access.usage}`),
+      ]),
+    ),
+    roughMipLevels,
+  };
+}
+
+function expectCompositionContract(
+  passes: readonly string[],
+  accesses: ReadonlyMap<string, readonly string[]>,
+): void {
+  expect(passes).toEqual([
+    'opaque-resolve',
+    'transmission-backdrop-copy',
+    'transmission-backdrop-mip',
+    'transmission-backdrop-mip-2',
+    'transmission-backdrop-mip-3',
+    'transmission-forward',
+    'transparent',
+    'temporal',
+  ]);
+  expect(accesses.get('transmission-backdrop-copy')).toEqual([
+    'opaque-resolved:copy-src',
+    'transmission-backdrop:copy-dst',
+  ]);
+}
+
+describe('transmission composition integration', () => {
+  it('keeps one shared backdrop copy before single-layer consumers', async () => {
+    const built = await buildComposition();
+
+    expect(built.graph.topology).toMatchObject({
+      active: true,
+      copyCount: 1,
+      mipCount: 1,
+      aliasCount: 0,
+    });
+    expectCompositionContract(built.passes, built.accesses);
+    expect(built.roughMipLevels).toEqual([1, 2, 3]);
+  });
+
+  it('falls back from edge or TIR refraction through environment to unrefracted color', () => {
+    expect(
+      resolveRefractionBackdrop({
+        uv: [0.01, 0.5],
+        refracted: [0.1, 0.2, 0.3],
+        environment: [0.4, 0.5, 0.6],
+        unrefracted: [0.7, 0.8, 0.9],
+      }),
+    ).toEqual({ source: 'environment', color: [0.4, 0.5, 0.6] });
+    expect(
+      resolveRefractionBackdrop({
+        uv: [0.01, 0.5],
+        unrefracted: [0.7, 0.8, 0.9],
+      }),
+    ).toEqual({ source: 'unrefracted', color: [0.7, 0.8, 0.9] });
+    expect(fresnelReflectance(0.5, 1.5)).toBe(1);
+  });
+
+  it('keeps transmission layers before ordinary BLEND in stable queue order', () => {
+    const ordered = sortDispatchByQueue([
+      { id: 'near-blend', queue: 3000 },
+      { id: 'near-transmission', queue: 2001 },
+      { id: 'far-transmission', queue: 2000 },
+    ]);
+    expect(ordered.map((entry) => entry.id)).toEqual([
+      'far-transmission',
+      'near-transmission',
+      'near-blend',
+    ]);
+  });
+
+  it.each([
+    [
+      'omitted-backdrop-copy',
+      (passes: readonly string[]) => passes.filter((name) => name !== 'transmission-backdrop-copy'),
+    ],
+    ['reversed-phase-order', (passes: readonly string[]) => [...passes].reverse()],
+  ] as const)('dev falsifier %s breaks the composition contract', async (_name, falsify) => {
+    const built = await buildComposition();
+    expect(() => expectCompositionContract(falsify(built.passes), built.accesses)).toThrow();
+  });
+
+  it('dev falsifier reactive-zero-coverage breaks the composition contract', async () => {
+    const built = await buildComposition();
+    expect(() =>
+      expectCompositionContract(
+        built.passes.filter((name) => name !== 'temporal'),
+        built.accesses,
+      ),
+    ).toThrow();
+  });
+});