@forgeax/engine-render 0.1.6 → 0.1.19

package/src/temporal/frame-coordinator.ts

@@ -0,0 +1,311 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { CameraSnapshot } from '../render-contract';
+import { classifySceneDataCoverage, type SceneDataContributor } from './coverage';
+import { type TaaHistoryAttempt, TaaHistoryStore } from './taa-history-store';
+import {
+  projectTemporalView,
+  type SubmittedTemporalView,
+  snapshotSubmittedTemporalView,
+  type TemporalView,
+} from './temporal-view';
+
+/** The only stages that may publish a temporal frame. */
+export type TemporalFrameStage = 'build' | 'encode' | 'finish' | 'submit';
+
+export type TemporalFrameErrorCode = 'taa-unavailable' | 'temporal-active' | 'temporal-not-active';
+
+export interface TemporalFrameError {
+  readonly code: TemporalFrameErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail?: Readonly<Record<string, unknown>>;
+}
+
+export interface TemporalFrameSnapshot<T = unknown> {
+  readonly epoch: number;
+  readonly previous: T | undefined;
+  readonly historyAttempt: 'none' | 'active' | 'committed' | 'aborted';
+  readonly attempt: 'none' | 'active' | 'committed' | 'aborted';
+  readonly lastFailure: TemporalFrameStage | undefined;
+  readonly coverage: {
+    readonly exactContributorIds: readonly string[];
+    readonly reactiveContributorIds: readonly string[];
+    readonly missingContributorIds: readonly string[];
+    readonly omittedMissingContributorCount: number;
+  };
+}
+
+export interface TemporalFrameBeginInput<T = unknown> {
+  readonly current: T;
+  readonly antialias: 'none' | 'fxaa' | 'msaa' | 'taa';
+  /** Enables the shared transaction for a temporal feature without TAA. */
+  readonly temporalDemand?: boolean;
+  readonly available?: boolean;
+  readonly contributors?: readonly SceneDataContributor[];
+  readonly requiredContributorIds?: readonly string[];
+  /** Projection produced before record uploads; it commits with the frame. */
+  readonly temporalView?: TemporalView;
+}
+
+export interface TemporalFrameCandidate<T = unknown> {
+  readonly epoch: number;
+  readonly current: T;
+  readonly previous: T | undefined;
+  readonly history: { readonly direction: 'a-to-b' | 'b-to-a'; readonly valid: boolean };
+  readonly contributors: readonly SceneDataContributor[];
+  readonly requiredContributorIds: readonly string[];
+  readonly temporalView?: TemporalView;
+}
+
+export interface TemporalFramePhases<T = unknown> {
+  readonly build: () => T;
+  readonly encode: (built: T) => void;
+  readonly finish: () => void;
+  readonly submit: () => void;
+}
+
+export interface TemporalFrameReceipt<T = unknown> {
+  readonly epoch: number;
+  readonly previous: T;
+  readonly historyDirection: 'a-to-b' | 'b-to-a';
+}
+
+function failure(code: TemporalFrameErrorCode, hint: string): TemporalFrameError {
+  return {
+    code,
+    expected:
+      code === 'taa-unavailable'
+        ? 'TAA resources and capability are available'
+        : 'one temporal frame is active',
+    hint,
+  };
+}
+
+/**
+ * Renderer-owned temporal transaction. It has no graph or backend dependency:
+ * graph assembly supplies the four phase callbacks and only submit publishes
+ * the candidate snapshot.
+ */
+export class TemporalFrameCoordinator<T = unknown> {
+  readonly historyStore: TaaHistoryStore;
+  private epoch: number;
+  private previous: T | undefined;
+  private active: TemporalFrameCandidate<T> | undefined;
+  private attempt: TemporalFrameSnapshot<T>['attempt'] = 'none';
+  private historyAttempt: TemporalFrameSnapshot<T>['historyAttempt'] = 'none';
+  private lastFailure: TemporalFrameStage | undefined;
+  private historyDirection: 'a-to-b' | 'b-to-a' = 'a-to-b';
+  private temporalFrameIndex = 0;
+  private lastSubmittedView: SubmittedTemporalView | undefined;
+  private coverage: TemporalFrameSnapshot<T>['coverage'] = {
+    exactContributorIds: [],
+    reactiveContributorIds: [],
+    missingContributorIds: [],
+    omittedMissingContributorCount: 0,
+  };
+  private readonly historyAttempts = new WeakMap<object, TaaHistoryAttempt>();
+
+  constructor(
+    initial: {
+      readonly epoch?: number;
+      readonly previous?: T;
+      readonly historyStore?: TaaHistoryStore;
+    } = {},
+  ) {
+    this.historyStore = initial.historyStore ?? new TaaHistoryStore();
+    this.epoch = initial.epoch ?? 0;
+    this.previous = initial.previous;
+  }
+
+  begin(input: TemporalFrameBeginInput<T>): Result<TemporalFrameCandidate<T>, TemporalFrameError> {
+    const demanded = input.antialias === 'taa' || input.temporalDemand === true;
+    if (!demanded) {
+      return ok({
+        epoch: this.epoch,
+        current: input.current,
+        previous: this.previous,
+        history: { direction: this.historyDirection, valid: false },
+        contributors: Object.freeze([...(input.contributors ?? [])]),
+        requiredContributorIds: Object.freeze([...(input.requiredContributorIds ?? [])]),
+        ...(input.temporalView === undefined ? {} : { temporalView: input.temporalView }),
+      });
+    }
+    if (input.available === false) {
+      return err(
+        failure('taa-unavailable', 'enable rgba16float temporal targets and retry the frame'),
+      );
+    }
+    if (this.active !== undefined) {
+      return err(
+        failure(
+          'temporal-active',
+          'commit or abort the active temporal frame before beginning another',
+        ),
+      );
+    }
+    const candidate: TemporalFrameCandidate<T> = {
+      epoch: this.epoch + 1,
+      current: input.current,
+      previous: this.previous,
+      history: { direction: this.historyDirection, valid: this.previous !== undefined },
+      contributors: Object.freeze([...(input.contributors ?? [])]),
+      requiredContributorIds: Object.freeze([...(input.requiredContributorIds ?? [])]),
+      ...(input.temporalView === undefined ? {} : { temporalView: input.temporalView }),
+    };
+    if (input.antialias === 'taa') {
+      this.historyAttempts.set(candidate, this.historyStore.begin());
+    }
+    this.active = candidate;
+    this.attempt = 'active';
+    this.historyAttempt = input.antialias === 'taa' ? 'active' : 'none';
+    this.lastFailure = undefined;
+    return ok(candidate);
+  }
+
+  commit(
+    candidate: TemporalFrameCandidate<T>,
+  ): Result<TemporalFrameReceipt<T>, TemporalFrameError> {
+    if (this.active !== candidate) {
+      return err(failure('temporal-not-active', 'commit the candidate returned by begin'));
+    }
+    this.epoch = candidate.epoch;
+    this.previous = candidate.current;
+    if (candidate.temporalView !== undefined) {
+      this.lastSubmittedView = snapshotSubmittedTemporalView(candidate.temporalView);
+      this.temporalFrameIndex += 1;
+    }
+    this.historyDirection = candidate.history.direction === 'a-to-b' ? 'b-to-a' : 'a-to-b';
+    const historyAttempt = this.historyAttempts.get(candidate);
+    historyAttempt?.commit();
+    this.coverage = classifySceneDataCoverage({
+      contributors: candidate.contributors,
+      requiredContributorIds: candidate.requiredContributorIds,
+    });
+    this.active = undefined;
+    historyAttempt?.abort();
+    this.historyAttempts.delete(candidate);
+    this.attempt = 'committed';
+    this.historyAttempt = historyAttempt === undefined ? 'none' : 'committed';
+    return ok({
+      epoch: this.epoch,
+      previous: candidate.current,
+      historyDirection: candidate.history.direction,
+    });
+  }
+
+  abort(candidate: TemporalFrameCandidate<T>, stage: TemporalFrameStage = 'submit'): void {
+    if (this.active !== candidate) return;
+    this.historyAttempts.get(candidate)?.abort();
+    this.historyAttempts.delete(candidate);
+    this.active = undefined;
+    this.attempt = 'aborted';
+    this.historyAttempt = 'aborted';
+    this.lastFailure = stage;
+  }
+
+  run(
+    input: TemporalFrameBeginInput<T>,
+    phases: TemporalFramePhases<T>,
+  ): Result<TemporalFrameReceipt<T> | undefined, TemporalFrameError> {
+    const started = this.begin(input);
+    if (!started.ok) return started;
+    const candidate = started.value;
+    if (input.antialias !== 'taa' && input.temporalDemand !== true) return ok(undefined);
+    try {
+      const built = phases.build();
+      phases.encode(built);
+      phases.finish();
+      phases.submit();
+    } catch (cause) {
+      const stage = this.stageFromError(cause);
+      this.abort(candidate, stage);
+      return err({
+        code: 'temporal-not-active',
+        expected: `temporal ${stage} succeeds before commit`,
+        hint: 'inspect the underlying stage failure and retry the frame',
+        detail: { stage, cause },
+      });
+    }
+    return this.commit(candidate);
+  }
+
+  inspect(): TemporalFrameSnapshot<T> {
+    return {
+      epoch: this.epoch,
+      previous: this.previous,
+      historyAttempt: this.historyAttempt,
+      attempt: this.attempt,
+      lastFailure: this.lastFailure,
+      coverage: this.coverage,
+    };
+  }
+
+  /**
+   * Derive the current/previous camera matrices without mutating history.
+   * `commit()` is the only operation that publishes the returned view, so a
+   * graph/finish/submit failure leaves the last successful view intact.
+   */
+  prepareTemporalView(
+    camera: CameraSnapshot,
+    surfaceWidth: number,
+    surfaceHeight: number,
+  ): TemporalView | undefined {
+    const demanded =
+      camera.antialias === 'taa' ||
+      (camera.motionBlur?.shutterAngle !== undefined && camera.motionBlur.shutterAngle > 0);
+    if (!demanded) return undefined;
+    return projectTemporalView({
+      camera,
+      temporalFrameIndex: this.temporalFrameIndex,
+      surfaceWidth,
+      surfaceHeight,
+      ...(this.lastSubmittedView === undefined ? {} : { lastSubmitted: this.lastSubmittedView }),
+    });
+  }
+
+  reset(
+    reason:
+      | 'cut'
+      | 'resize'
+      | 'camera-switch'
+      | 'detach'
+      | 'recover'
+      | 'device-loss'
+      | 'device-generation' = 'recover',
+  ): void {
+    void reason;
+    this.active = undefined;
+    this.epoch = 0;
+    this.previous = undefined;
+    this.temporalFrameIndex = 0;
+    this.lastSubmittedView = undefined;
+    this.historyDirection = 'a-to-b';
+    this.historyStore.reset(
+      reason === 'cut' || reason === 'camera-switch'
+        ? 'camera-cut'
+        : reason === 'resize'
+          ? 'resize'
+          : reason === 'device-generation' || reason === 'device-loss'
+            ? 'device-generation'
+            : 'recover',
+    );
+    this.attempt = 'none';
+    this.historyAttempt = 'none';
+    this.lastFailure = undefined;
+    this.coverage = {
+      exactContributorIds: [],
+      reactiveContributorIds: [],
+      missingContributorIds: [],
+      omittedMissingContributorCount: 0,
+    };
+  }
+
+  private stageFromError(cause: unknown): TemporalFrameStage {
+    if (typeof cause === 'object' && cause !== null && 'stage' in cause) {
+      const stage = (cause as { stage?: unknown }).stage;
+      if (stage === 'build' || stage === 'encode' || stage === 'finish' || stage === 'submit')
+        return stage;
+    }
+    return 'submit';
+  }
+}

package/src/temporal/gpu.ts

@@ -0,0 +1,287 @@
+import type {
+  BindGroupLayout,
+  Buffer,
+  RhiDevice,
+  RhiQueue,
+  Sampler,
+  Texture,
+  TextureView,
+} from '@forgeax/engine-rhi';
+import type { DeviceScope } from '../device/device-scope';
+import {
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
+import type { RenderFrameState } from '../record/frame-snapshot';
+
+interface TemporalSurface {
+  readonly texture: Texture;
+  readonly view: TextureView;
+}
+
+export interface TemporalGpuState {
+  readonly device: RhiDevice;
+  readonly scope: DeviceScope;
+  readonly childScope: DeviceScope;
+  width: number;
+  height: number;
+  valid: boolean;
+  readIndex: 0 | 1;
+  pendingIndex: 0 | 1 | undefined;
+  readonly color: [TemporalSurface, TemporalSurface];
+  readonly temporal: [TemporalSurface, TemporalSurface];
+  bindGroupLayout: BindGroupLayout | undefined;
+  sampler: Sampler | undefined;
+  paramsBuffer: Buffer | undefined;
+  committed: boolean;
+}
+
+function createSurface(
+  device: RhiDevice,
+  childScope: DeviceScope,
+  label: string,
+  width: number,
+  height: number,
+): TemporalSurface {
+  const texture = device.createTexture({
+    label,
+    size: { width, height, depthOrArrayLayers: 1 },
+    format: 'rgba16float',
+    textureBindingViewDimension: undefined,
+    usage:
+      GPU_TEXTURE_USAGE_COPY_SRC |
+      GPU_TEXTURE_USAGE_RENDER_ATTACHMENT |
+      GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+  });
+  if (!texture.ok) throw texture.error;
+  childScope._adopt('texture', texture.value, (value) => {
+    device.destroyTexture(value);
+  });
+  const view = device.createTextureView(texture.value, {
+    label: `${label}.view`,
+    dimension: '2d',
+    baseMipLevel: 0,
+    mipLevelCount: 1,
+    baseArrayLayer: 0,
+    arrayLayerCount: 1,
+  });
+  if (!view.ok) throw view.error;
+  return { texture: texture.value, view: view.value };
+}
+
+function createState(
+  device: RhiDevice,
+  scope: DeviceScope,
+  width: number,
+  height: number,
+): TemporalGpuState {
+  const childScope = scope.createChild(`${scope.owner}:temporal`);
+  try {
+    return {
+      device,
+      scope,
+      childScope,
+      width,
+      height,
+      valid: false,
+      readIndex: 0,
+      pendingIndex: undefined,
+      color: [
+        createSurface(device, childScope, 'taa-history-color-a', width, height),
+        createSurface(device, childScope, 'taa-history-color-b', width, height),
+      ],
+      temporal: [
+        createSurface(device, childScope, 'taa-history-temporal-a', width, height),
+        createSurface(device, childScope, 'taa-history-temporal-b', width, height),
+      ],
+      bindGroupLayout: undefined,
+      sampler: undefined,
+      paramsBuffer: undefined,
+      committed: false,
+    };
+  } catch (cause) {
+    childScope.abandon();
+    throw cause;
+  }
+}
+
+export function getTemporalParamsBuffer(state: TemporalGpuState): Buffer {
+  if (state.paramsBuffer !== undefined) return state.paramsBuffer;
+  const created = state.device.createBuffer({
+    label: 'taa-resolve-params',
+    size: 16,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    mappedAtCreation: false,
+  });
+  if (!created.ok) {
+    if (!state.committed) state.childScope.abandon();
+    throw created.error;
+  }
+  state.childScope._adopt('buffer', created.value, (value) => {
+    state.device.destroyBuffer(value);
+  });
+  const written = state.device.queue.writeBuffer(created.value, 0, new Uint8Array(16));
+  if (!written.ok) {
+    if (!state.committed) state.childScope.abandon();
+    throw written.error;
+  }
+  state.paramsBuffer = created.value;
+  return created.value;
+}
+
+export function getTemporalGpuState(
+  frameState: RenderFrameState,
+  device: RhiDevice,
+  scope: DeviceScope,
+  width: number,
+  height: number,
+): TemporalGpuState {
+  const staged = frameState.temporalGpuState;
+  if (
+    staged !== undefined &&
+    staged.scope === scope &&
+    staged.width === width &&
+    staged.height === height
+  ) {
+    return staged;
+  }
+  const existing = frameState.activeTemporalGpuState;
+  if (
+    existing !== undefined &&
+    existing.scope === scope &&
+    existing.width === width &&
+    existing.height === height
+  ) {
+    return existing;
+  }
+  const next = createState(device, scope, width, height);
+  frameState.temporalGpuState = next;
+  return next;
+}
+
+export function getTemporalBindGroupResources(state: TemporalGpuState): {
+  readonly layout: BindGroupLayout;
+  readonly sampler: Sampler | null;
+} {
+  if (state.bindGroupLayout !== undefined) {
+    return {
+      layout: state.bindGroupLayout,
+      sampler: state.sampler ?? null,
+    };
+  }
+  try {
+    const layout = state.device.createBindGroupLayout({
+      label: 'taa-resolve-bind-group',
+      entries: [
+        {
+          binding: 0,
+          visibility: 2,
+          texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+        },
+        { binding: 1, visibility: 2, sampler: { type: 'non-filtering' } },
+        {
+          binding: 2,
+          visibility: 2,
+          texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+        },
+        { binding: 3, visibility: 2, sampler: { type: 'non-filtering' } },
+        {
+          binding: 4,
+          visibility: 2,
+          texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+        },
+        { binding: 5, visibility: 2, sampler: { type: 'non-filtering' } },
+        {
+          binding: 6,
+          visibility: 2,
+          texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+        },
+        { binding: 7, visibility: 2, sampler: { type: 'non-filtering' } },
+        { binding: 8, visibility: 2, buffer: { type: 'uniform' } },
+      ],
+    });
+    if (!layout.ok) throw layout.error;
+    state.childScope._adopt('binding', layout.value, () => undefined);
+    const sampler = state.device.createSampler({
+      addressModeU: 'clamp-to-edge',
+      addressModeV: 'clamp-to-edge',
+      magFilter: 'nearest',
+      minFilter: 'nearest',
+    });
+    if (!sampler.ok) throw sampler.error;
+    state.childScope._adopt('binding', sampler.value, () => undefined);
+    state.bindGroupLayout = layout.value;
+    state.sampler = sampler.value;
+    return { layout: layout.value, sampler: sampler.value };
+  } catch (cause) {
+    if (!state.committed) {
+      state.childScope.abandon();
+      state.bindGroupLayout = undefined;
+      state.sampler = undefined;
+    }
+    throw cause;
+  }
+}
+
+export function temporalReadIndex(state: TemporalGpuState): 0 | 1 {
+  return state.readIndex;
+}
+
+export function temporalWriteIndex(state: TemporalGpuState): 0 | 1 {
+  return state.readIndex === 0 ? 1 : 0;
+}
+
+export function stageTemporalGpuSubmit(state: TemporalGpuState): void {
+  state.pendingIndex = state.readIndex === 0 ? 1 : 0;
+}
+
+export function hasPendingTemporalGpuSubmit(state: TemporalGpuState): boolean {
+  return state.pendingIndex !== undefined;
+}
+
+export function commitTemporalGpuSubmit(state: TemporalGpuState): boolean {
+  if (state.pendingIndex === undefined) return false;
+  state.readIndex = state.pendingIndex;
+  state.pendingIndex = undefined;
+  state.valid = true;
+  state.committed = true;
+  return true;
+}
+
+export function abortTemporalGpuSubmit(state: TemporalGpuState): void {
+  state.pendingIndex = undefined;
+}
+
+export function retireTemporalGpuState(state: TemporalGpuState): void {
+  state.pendingIndex = undefined;
+  state.childScope.retire();
+  state.valid = false;
+  state.committed = false;
+  state.bindGroupLayout = undefined;
+  state.sampler = undefined;
+  state.paramsBuffer = undefined;
+}
+
+export function retireTemporalGpuStateAfterFence(
+  state: TemporalGpuState,
+  queue: RhiQueue,
+  retiring: Set<TemporalGpuState>,
+  onFailure: (cause: unknown) => void,
+): void {
+  if (state.childScope.state === 'retired' || state.childScope.state === 'abandoned') return;
+  state.childScope.beginRetire();
+  retiring.add(state);
+  void queue.onSubmittedWorkDone().then(
+    () => {
+      retiring.delete(state);
+      retireTemporalGpuState(state);
+    },
+    (cause) => {
+      retiring.delete(state);
+      onFailure(cause);
+      retireTemporalGpuState(state);
+    },
+  );
+}

package/src/temporal/history.ts

@@ -0,0 +1,92 @@
+import type { DeviceScope, ResourceRef } from '../device/device-scope';
+import { createTemporalCoverage, type TemporalCoverage } from './coverage';
+import type { TemporalView } from './view';
+
+export type TemporalProducer = 'rigid' | 'instance' | 'skin' | 'morph' | 'transparent' | 'vfx';
+export type TemporalProducerState = Partial<Record<TemporalProducer, string>>;
+
+export interface TemporalHistorySnapshot {
+  readonly historyValid: boolean;
+  readonly frameIndex: number;
+  readonly previous: TemporalProducerState;
+  readonly coverage: TemporalCoverage;
+  readonly resetReason: string | undefined;
+}
+
+interface HistoryOptions {
+  readonly width: number;
+  readonly height: number;
+  readonly mode: 'off' | 'taa';
+}
+
+export class TemporalHistory {
+  readonly childScope: DeviceScope | undefined;
+  readonly coverage: TemporalCoverage;
+  readonly historyCount: number;
+  readonly historyBytes: number;
+  private readonly resources: readonly ResourceRef<object>[];
+  private current: TemporalProducerState = {};
+  private pending: TemporalProducerState | undefined;
+  private valid = false;
+  private index = 0;
+  private resetReason: string | undefined;
+
+  constructor(scope: DeviceScope, options: HistoryOptions) {
+    const taa = options.mode === 'taa';
+    this.coverage = taa
+      ? createTemporalCoverage(options.width, options.height)
+      : Object.freeze({
+          width: options.width,
+          height: options.height,
+          bytes: 0,
+          fullScreen: true as const,
+        });
+    this.historyCount = taa ? 4 : 0;
+    this.historyBytes = this.coverage.bytes;
+    if (!taa) {
+      this.resources = [];
+      return;
+    }
+    const child = scope.createChild(`${scope.owner}:temporal-history`);
+    this.childScope = child;
+    this.resources = Object.freeze([
+      child.ref('texture', Object.freeze({ slot: 'color-a' })),
+      child.ref('texture', Object.freeze({ slot: 'color-b' })),
+      child.ref('texture', Object.freeze({ slot: 'temporal-a' })),
+      child.ref('texture', Object.freeze({ slot: 'temporal-b' })),
+    ]);
+  }
+
+  stage(view: TemporalView, producers: TemporalProducerState): void {
+    if (view.mode !== 'taa' || this.historyCount === 0) return;
+    this.pending = { ...producers };
+    this.resetReason = undefined;
+  }
+
+  commit(): void {
+    if (this.pending === undefined) return;
+    this.current = Object.freeze({ ...this.pending });
+    this.pending = undefined;
+    this.valid = true;
+    this.index += 1;
+  }
+
+  abort(reason: string = 'submit-failure'): void {
+    this.pending = undefined;
+    this.resetReason = reason;
+  }
+
+  snapshot(): TemporalHistorySnapshot {
+    return Object.freeze({
+      historyValid: this.valid,
+      frameIndex: this.index,
+      previous: Object.freeze({ ...this.current }),
+      coverage: this.coverage,
+      resetReason: this.resetReason,
+    });
+  }
+
+  get resourceRefs(): readonly ResourceRef<object>[] {
+    return this.resources;
+  }
+}

package/src/temporal/index.ts

@@ -0,0 +1,6 @@
+export * from './coverage';
+export { TemporalFrameCoordinator } from './frame-coordinator';
+export * from './scene-data';
+export * from './scene-data-catalog';
+export * from './standard-scene-data';
+export * from './temporal-view';