@forgeax/engine-render 0.1.6 → 0.1.19

package/src/temporal/taa-history-resources.ts

@@ -0,0 +1,128 @@
+import type {
+  RhiDevice,
+  RhiError,
+  Texture,
+  TextureDescriptor,
+  TextureView,
+} from '@forgeax/engine-rhi';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
+
+const HISTORY_USAGE =
+  GPU_TEXTURE_USAGE_COPY_SRC |
+  GPU_TEXTURE_USAGE_COPY_DST |
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING |
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT;
+
+export interface TaaHistorySlot {
+  readonly texture: Texture;
+  readonly view: TextureView;
+}
+
+export interface TaaHistoryResources {
+  readonly width: number;
+  readonly height: number;
+  readonly descriptor: TextureDescriptor;
+  readonly slots: readonly [TaaHistorySlot, TaaHistorySlot];
+  readonly temporalSlots: readonly [TaaHistorySlot, TaaHistorySlot];
+  readonly currentIndex: 0 | 1;
+  readonly previousIndex: 0 | 1;
+  readonly valid: boolean;
+  beginFrame(): void;
+  commitFrame(): void;
+  abortFrame(): void;
+  dispose(): void;
+}
+
+export function createTaaHistoryResources(
+  device: RhiDevice,
+  width: number,
+  height: number,
+): Result<TaaHistoryResources, RhiError> {
+  const descriptor: TextureDescriptor = {
+    label: 'taa-history-rgba16float',
+    size: { width, height, depthOrArrayLayers: 1 },
+    format: 'rgba16float',
+    usage: HISTORY_USAGE,
+    sampleCount: 1,
+    mipLevelCount: undefined,
+    dimension: undefined,
+    viewFormats: undefined,
+    textureBindingViewDimension: undefined,
+  };
+  const createSlots = (kind: 'color' | 'temporal'): Result<TaaHistorySlot[], RhiError> => {
+    const slots: TaaHistorySlot[] = [];
+    for (let index = 0; index < 2; index += 1) {
+      const texture = device.createTexture({
+        ...descriptor,
+        label: `taa-history-${kind}-rgba16float-${index}`,
+      });
+      if (!texture.ok) {
+        for (const slot of slots) device.destroyTexture(slot.texture);
+        return texture;
+      }
+      const view = device.createTextureView(texture.value, {
+        label: `taa-history-${kind}-rgba16float-${index}.view`,
+        dimension: '2d',
+      });
+      if (!view.ok) {
+        device.destroyTexture(texture.value);
+        for (const slot of slots) device.destroyTexture(slot.texture);
+        return err(view.error);
+      }
+      slots.push({ texture: texture.value, view: view.value });
+    }
+    return ok(slots);
+  };
+  const colorSlots = createSlots('color');
+  if (!colorSlots.ok) return colorSlots;
+  const temporalSlots = createSlots('temporal');
+  if (!temporalSlots.ok) {
+    for (const slot of colorSlots.value) device.destroyTexture(slot.texture);
+    return temporalSlots;
+  }
+
+  let currentIndex: 0 | 1 = 0;
+  let valid = false;
+  let active = false;
+  let disposed = false;
+  return ok({
+    width,
+    height,
+    descriptor,
+    slots: colorSlots.value as [TaaHistorySlot, TaaHistorySlot],
+    temporalSlots: temporalSlots.value as [TaaHistorySlot, TaaHistorySlot],
+    get currentIndex() {
+      return currentIndex;
+    },
+    get previousIndex() {
+      return currentIndex === 0 ? 1 : 0;
+    },
+    get valid() {
+      return valid;
+    },
+    beginFrame() {
+      active = true;
+    },
+    commitFrame() {
+      if (!active || disposed) return;
+      currentIndex = currentIndex === 0 ? 1 : 0;
+      valid = true;
+      active = false;
+    },
+    abortFrame() {
+      active = false;
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const slot of colorSlots.value) device.destroyTexture(slot.texture);
+      for (const slot of temporalSlots.value) device.destroyTexture(slot.texture);
+    },
+  });
+}

package/src/temporal/taa-history-store.ts

@@ -0,0 +1,79 @@
+export type TaaHistoryResetReason =
+  | 'first-frame'
+  | 'camera-cut'
+  | 'resize'
+  | 'recover'
+  | 'device-generation';
+
+export interface TaaHistoryInspection {
+  readonly generation: number;
+  readonly seed: number;
+  readonly attempt: 'none' | 'active' | 'committed' | 'aborted';
+  readonly valid: boolean;
+  readonly resetReason: TaaHistoryResetReason | undefined;
+}
+
+export interface TaaHistoryAttempt {
+  readonly generation: number;
+  readonly seed: number;
+  commit(): void;
+  abort(): void;
+}
+
+/** TAA-only history owner. No global registry or backend handle crosses this boundary. */
+export class TaaHistoryStore {
+  private generation = 0;
+  private seed = 0;
+  private valid = false;
+  private attempt: TaaHistoryInspection['attempt'] = 'none';
+  private resetReason: TaaHistoryResetReason | undefined;
+
+  begin(reason: TaaHistoryResetReason | undefined = undefined): TaaHistoryAttempt {
+    const generation = this.generation;
+    const seed = this.seed;
+    this.attempt = 'active';
+    let state: 'active' | 'committed' | 'aborted' = 'active';
+    return {
+      generation,
+      seed,
+      commit: () => {
+        if (state !== 'active') return;
+        state = 'committed';
+        this.attempt = 'committed';
+        this.valid = true;
+        this.generation += 1;
+        this.seed += 1;
+        this.resetReason = reason;
+      },
+      abort: () => {
+        if (state !== 'active') return;
+        state = 'aborted';
+        this.attempt = 'aborted';
+      },
+    };
+  }
+
+  seedHistory(reason: TaaHistoryResetReason = 'first-frame'): void {
+    this.valid = false;
+    this.resetReason = reason;
+    this.attempt = 'none';
+  }
+
+  reset(reason: TaaHistoryResetReason): void {
+    this.generation = 0;
+    this.seed = 0;
+    this.valid = false;
+    this.attempt = 'none';
+    this.resetReason = reason;
+  }
+
+  inspect(): TaaHistoryInspection {
+    return {
+      generation: this.generation,
+      seed: this.seed,
+      attempt: this.attempt,
+      valid: this.valid,
+      resetReason: this.resetReason,
+    };
+  }
+}

package/src/temporal/taa-resolve.ts

@@ -0,0 +1,34 @@
+import type { RenderPipelineFeatureTarget, RenderPipelineTarget } from '../render-pipeline';
+
+export interface TaaResolveInput {
+  readonly current: RenderPipelineFeatureTarget;
+  readonly temporal: RenderPipelineFeatureTarget;
+  readonly historyValid: boolean;
+}
+
+export interface TaaResolveInspection {
+  readonly applied: boolean;
+  readonly currentOnly: boolean;
+  readonly historyGeneration: number;
+}
+
+/** TAA resolve contract; graph encoding remains owned by Standard topology. */
+export function resolveTaa(
+  input: TaaResolveInput,
+  historyGeneration: number,
+): TaaResolveInspection {
+  return {
+    applied: input.historyValid,
+    currentOnly: !input.historyValid,
+    historyGeneration,
+  };
+}
+
+export function taaOutputTarget(target: RenderPipelineFeatureTarget): RenderPipelineTarget {
+  return {
+    texture: target.texture,
+    view: target.view,
+    format: 'rgba16float',
+    sampleCount: 1,
+  };
+}

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 },
+    });
+  });
+});