@forgeax/engine-render 0.1.2

package/src/temporal-coverage.ts

@@ -0,0 +1,106 @@
+export type TemporalCoverageClass = 'exact' | 'reactive' | 'missing';
+
+export const TEMPORAL_PRODUCER_LANES = Object.freeze([
+  'rigid',
+  'instances',
+  'skinning',
+  'morph',
+  'alpha-cutout',
+  'transparent',
+  'sprite',
+  'vfx',
+  'custom-deformation',
+  'render-feature',
+] as const);
+
+export type TemporalProducerLane = (typeof TEMPORAL_PRODUCER_LANES)[number];
+
+export const TEMPORAL_REACTIVE_REASONS = Object.freeze([
+  'first-observation',
+  'visibility-reentry',
+  'generation-reuse',
+  'geometry-revision',
+  'material-revision',
+  'unsupported-previous-deformation',
+  'producer-reactive-fallback',
+] as const);
+
+export type TemporalReactiveReason = (typeof TEMPORAL_REACTIVE_REASONS)[number];
+
+export const TEMPORAL_MISSING_REASONS = Object.freeze([
+  'previous-state-unavailable',
+  'dispatch-unavailable',
+  'feature-coverage-undeclared',
+  'exact-target-unwritten',
+] as const);
+
+export type TemporalMissingReason = (typeof TEMPORAL_MISSING_REASONS)[number];
+
+interface TemporalCoverageContributionBase {
+  /** Stable renderer or RenderFeature identity, never a frame-local array index alone. */
+  readonly identity: string;
+  readonly lane: TemporalProducerLane;
+}
+
+export type TemporalCoverageContribution =
+  | (TemporalCoverageContributionBase & {
+      readonly coverage: 'exact';
+      readonly previous: 'last-submitted' | 'current-seed';
+    })
+  | (TemporalCoverageContributionBase & {
+      readonly coverage: 'reactive';
+      readonly reason: TemporalReactiveReason;
+    })
+  | (TemporalCoverageContributionBase & {
+      readonly coverage: 'missing';
+      readonly reason: TemporalMissingReason;
+    });
+
+export interface TemporalCoverageSummary {
+  readonly complete: boolean;
+  readonly exact: number;
+  readonly reactive: number;
+  readonly missing: number;
+  readonly missingContributors: readonly string[];
+  readonly contributors: readonly TemporalCoverageContribution[];
+}
+
+export const EMPTY_TEMPORAL_COVERAGE: TemporalCoverageSummary = Object.freeze({
+  complete: true,
+  exact: 0,
+  reactive: 0,
+  missing: 0,
+  missingContributors: Object.freeze([]),
+  contributors: Object.freeze([]),
+});
+
+/** Collapse one-class-per-identity producer facts into the frame coverage authority. */
+export function summarizeTemporalCoverage(
+  contributions: readonly TemporalCoverageContribution[],
+): TemporalCoverageSummary {
+  const byIdentity = new Map<string, TemporalCoverageContribution>();
+  for (const contribution of contributions) {
+    if (byIdentity.has(contribution.identity)) {
+      throw new RangeError(`duplicate temporal contributor identity: ${contribution.identity}`);
+    }
+    byIdentity.set(contribution.identity, contribution);
+  }
+  const contributors = Object.freeze([...byIdentity.values()]);
+  const exact = contributors.filter((contribution) => contribution.coverage === 'exact').length;
+  const reactive = contributors.filter(
+    (contribution) => contribution.coverage === 'reactive',
+  ).length;
+  const missingContributors = Object.freeze(
+    contributors.flatMap((contribution) =>
+      contribution.coverage === 'missing' ? [contribution.identity] : [],
+    ),
+  );
+  return Object.freeze({
+    complete: missingContributors.length === 0,
+    exact,
+    reactive,
+    missing: missingContributors.length,
+    missingContributors,
+    contributors,
+  });
+}

package/src/temporal-frame-transaction.ts

@@ -0,0 +1,301 @@
+import { markSceneReactiveRevision } from './features/scene-temporal';
+import type {
+  RenderSceneProjection,
+  RenderSceneSubmissionCapture,
+  RenderSceneSubmissionDelta,
+} from './render-scene-projection';
+import type { CameraSnapshot, RenderableSnapshot } from './render-system-extract';
+import type {
+  TaaHistoryFrameAttempt,
+  TaaHistoryInspection,
+  TaaHistoryResetReason,
+  TaaHistoryStore,
+} from './taa-history-store';
+import { EMPTY_TEMPORAL_COVERAGE, type TemporalCoverageSummary } from './temporal-coverage';
+import {
+  projectTemporalView,
+  type SubmittedTemporalView,
+  snapshotSubmittedTemporalView,
+  type TemporalView,
+} from './temporal-view';
+
+export type TemporalHistoryDirection = 'a-to-b' | 'b-to-a';
+export type TemporalFrameAttemptStatus = 'active' | 'committed' | 'aborted';
+export type TemporalSubmitAbortStage =
+  | 'graph-unavailable'
+  | 'graph-execute'
+  | 'encoder-finish'
+  | 'submission-plan'
+  | 'queue-submit'
+  | 'frame-exit';
+export type TemporalFrameFailure =
+  | { readonly kind: 'capability'; readonly code: 'taa-caps-insufficient' }
+  | { readonly kind: 'pipeline'; readonly code: 'temporal-unsupported' | 'graph-build-failed' }
+  | { readonly kind: 'submit-abort'; readonly stage: TemporalSubmitAbortStage }
+  | { readonly kind: 'device-recovery'; readonly code: 'device-recovery' };
+
+export interface TemporalFrameTransactionInspection {
+  readonly active: boolean;
+  readonly temporalFrameIndex: number;
+  readonly historyDirection: TemporalHistoryDirection;
+  readonly historyValid: boolean;
+  readonly lastSubmittedView: SubmittedTemporalView | undefined;
+  readonly history: TaaHistoryInspection;
+  readonly coverage: TemporalCoverageSummary;
+  readonly lastResetReason: TaaHistoryResetReason | undefined;
+  readonly lastJitter:
+    | {
+        readonly currentUv: readonly [number, number];
+        readonly previousUv: readonly [number, number];
+      }
+    | undefined;
+  readonly lastFailure: TemporalFrameFailure | undefined;
+  readonly environmentSignature?: string | undefined;
+  readonly environmentResetCount?: number;
+  readonly environmentPublishCount?: number;
+}
+
+export interface TemporalFrameBeginInput {
+  readonly camera: CameraSnapshot;
+  readonly surfaceWidth: number;
+  readonly surfaceHeight: number;
+  readonly projection: RenderSceneProjection;
+  readonly visible: readonly RenderableSnapshot[];
+  readonly coverage?: TemporalCoverageSummary;
+  /** Optional successful-submit comparison token for an existing reactive lane. */
+  readonly reactiveRevision?: number | undefined;
+  /** Active environment identity supplied by the existing temporal owner. */
+  readonly environmentSignature?: string | undefined;
+  readonly onSceneSubmitted?: ((delta: RenderSceneSubmissionDelta) => void) | undefined;
+}
+
+export interface TemporalFrameAttempt {
+  readonly view: TemporalView | undefined;
+  readonly historyDirection: TemporalHistoryDirection;
+  readonly historyValid: boolean;
+  readonly reactiveRevisionChanged: boolean;
+  readonly environmentSignature: string | undefined;
+  readonly status: TemporalFrameAttemptStatus;
+  commit(): void;
+  abort(stage?: TemporalSubmitAbortStage): void;
+}
+
+interface ActiveTemporalFrame {
+  readonly projection: RenderSceneProjection;
+  readonly scene: RenderSceneSubmissionCapture;
+  readonly view: TemporalView | undefined;
+  readonly historyDirection: TemporalHistoryDirection;
+  readonly history: TaaHistoryFrameAttempt;
+  readonly coverage: TemporalCoverageSummary;
+  readonly reactiveRevision: number | undefined;
+  readonly hasReactiveRevision: boolean;
+  readonly reactiveRevisionChanged: boolean;
+  readonly onSceneSubmitted: ((delta: RenderSceneSubmissionDelta) => void) | undefined;
+  readonly environmentSignature: string | undefined;
+  readonly environmentChanged: boolean;
+  readonly historyValid: boolean;
+}
+
+/** The renderer's single successful-submit authority for all temporal state. */
+export class TemporalFrameTransaction {
+  private active: ActiveTemporalFrame | undefined;
+  private temporalFrameIndex = 0;
+  private lastSubmittedView: SubmittedTemporalView | undefined;
+  private lastSubmittedCoverage = EMPTY_TEMPORAL_COVERAGE;
+  private lastSubmittedReactiveRevision: number | undefined;
+  private hasSubmittedReactiveRevision = false;
+  private lastResetReason: TaaHistoryResetReason | undefined;
+  private lastJitter:
+    | {
+        readonly currentUv: readonly [number, number];
+        readonly previousUv: readonly [number, number];
+      }
+    | undefined;
+  private lastFailure: TemporalFrameFailure | undefined;
+  private environmentSignature: string | undefined;
+  private environmentResetCount = 0;
+  private environmentPublishCount = 0;
+
+  constructor(readonly historyStore: TaaHistoryStore) {}
+
+  begin(input: TemporalFrameBeginInput): TemporalFrameAttempt {
+    if (this.active !== undefined) {
+      throw new RangeError('a temporal frame transaction is already active');
+    }
+    const view =
+      input.camera.antialias === 'taa'
+        ? projectTemporalView({
+            camera: input.camera,
+            temporalFrameIndex: this.temporalFrameIndex,
+            surfaceWidth: input.surfaceWidth,
+            surfaceHeight: input.surfaceHeight,
+            ...(this.lastSubmittedView === undefined
+              ? {}
+              : { lastSubmitted: this.lastSubmittedView }),
+          })
+        : undefined;
+    const coverageBeforeRevision = input.coverage ?? EMPTY_TEMPORAL_COVERAGE;
+    const hasReactiveRevision = Object.hasOwn(input, 'reactiveRevision');
+    const reactiveRevisionChanged =
+      hasReactiveRevision &&
+      (!this.hasSubmittedReactiveRevision ||
+        !Object.is(this.lastSubmittedReactiveRevision, input.reactiveRevision));
+    const coverage = markSceneReactiveRevision(coverageBeforeRevision, reactiveRevisionChanged);
+    const history = this.historyStore.beginFrame(view, coverage.complete);
+    const environmentChanged = input.environmentSignature !== this.environmentSignature;
+    const frame: ActiveTemporalFrame = {
+      projection: input.projection,
+      scene: input.projection.captureSubmission(input.visible),
+      view,
+      historyDirection: history.direction,
+      history,
+      coverage,
+      reactiveRevision: input.reactiveRevision,
+      hasReactiveRevision,
+      reactiveRevisionChanged,
+      onSceneSubmitted: input.onSceneSubmitted,
+      environmentSignature: input.environmentSignature,
+      environmentChanged,
+      // A candidate environment is not published until the shared queue
+      // submission succeeds. Disable old history for this frame without
+      // mutating the store, so an aborted candidate keeps the old LKG history.
+      historyValid: history.valid && !environmentChanged,
+    };
+    this.active = frame;
+    let status: TemporalFrameAttemptStatus = 'active';
+    return {
+      view,
+      historyDirection: frame.historyDirection,
+      historyValid: frame.historyValid && !frame.reactiveRevisionChanged,
+      reactiveRevisionChanged: frame.reactiveRevisionChanged,
+      environmentSignature: frame.environmentSignature,
+      get status() {
+        return status;
+      },
+      commit: () => {
+        if (status !== 'active') return;
+        this.commit(frame);
+        status = 'committed';
+      },
+      abort: (stage = 'frame-exit') => {
+        if (status !== 'active') return;
+        this.abort(frame, stage);
+        status = 'aborted';
+      },
+    };
+  }
+
+  inspect(): TemporalFrameTransactionInspection {
+    const history = this.historyStore.inspect();
+    return {
+      active: this.active !== undefined,
+      temporalFrameIndex: this.temporalFrameIndex,
+      historyDirection: history.direction,
+      historyValid: history.valid,
+      lastSubmittedView: this.lastSubmittedView,
+      history,
+      coverage: this.lastSubmittedCoverage,
+      lastResetReason: this.lastResetReason,
+      lastJitter: this.lastJitter,
+      lastFailure: this.lastFailure,
+      environmentSignature: this.environmentSignature,
+      environmentResetCount: this.environmentResetCount,
+      environmentPublishCount: this.environmentPublishCount,
+    };
+  }
+
+  /**
+   * Called only by the successful active-environment publish boundary. A
+   * desired candidate, failed build, or LKG retry never reaches this method.
+   */
+  noteEnvironmentPublished(signature: string | undefined): void {
+    if (this.environmentSignature === signature) return;
+    this.environmentSignature = signature;
+    this.environmentPublishCount += 1;
+    this.environmentResetCount += 1;
+    this.lastResetReason = 'environment-published';
+    // During a successful frame commit, the attempt already disables old
+    // history and will seed the new history target. Invalidating here would
+    // discard that same-frame seed and cause a second unnecessary reset. Keep
+    // the immediate invalidation for external publication notifications.
+    if (this.active === undefined) this.historyStore.invalidate('environment-published');
+  }
+
+  notePipelineFailure(
+    kind: 'capability' | 'pipeline',
+    code: 'temporal-unsupported' | 'graph-build-failed' = 'graph-build-failed',
+  ): void {
+    this.lastFailure =
+      kind === 'capability' ? { kind, code: 'taa-caps-insufficient' } : { kind, code };
+  }
+
+  resetForRecover(): void {
+    this.active?.history.abort();
+    this.active = undefined;
+    this.temporalFrameIndex = 0;
+    this.lastSubmittedView = undefined;
+    this.lastSubmittedCoverage = EMPTY_TEMPORAL_COVERAGE;
+    this.lastSubmittedReactiveRevision = undefined;
+    this.hasSubmittedReactiveRevision = false;
+    this.lastResetReason = 'device-recovery';
+    this.lastJitter = undefined;
+    this.lastFailure = { kind: 'device-recovery', code: 'device-recovery' };
+    this.environmentSignature = undefined;
+    this.historyStore.resetForRecover();
+  }
+
+  dispose(): void {
+    if (this.active !== undefined) this.active.history.abort();
+    this.active = undefined;
+    this.temporalFrameIndex = 0;
+    this.lastSubmittedView = undefined;
+    this.lastSubmittedCoverage = EMPTY_TEMPORAL_COVERAGE;
+    this.lastSubmittedReactiveRevision = undefined;
+    this.hasSubmittedReactiveRevision = false;
+    this.lastResetReason = undefined;
+    this.lastJitter = undefined;
+    this.lastFailure = undefined;
+    this.environmentSignature = undefined;
+    this.environmentResetCount = 0;
+    this.environmentPublishCount = 0;
+    this.historyStore.dispose();
+  }
+
+  private commit(frame: ActiveTemporalFrame): void {
+    if (this.active !== frame) return;
+    const sceneDelta = frame.projection.commitSubmission(frame.scene);
+    if (frame.environmentChanged) this.noteEnvironmentPublished(frame.environmentSignature);
+    if (frame.view === undefined) {
+      this.temporalFrameIndex = 0;
+      this.lastSubmittedView = undefined;
+      this.lastResetReason = frame.environmentChanged ? 'environment-published' : undefined;
+      this.lastJitter = undefined;
+    } else {
+      this.lastSubmittedView = snapshotSubmittedTemporalView(frame.view);
+      this.temporalFrameIndex += 1;
+      this.lastResetReason = frame.environmentChanged
+        ? 'environment-published'
+        : frame.history.resetReason;
+      this.lastJitter = {
+        currentUv: [frame.view.currentJitterUv[0], frame.view.currentJitterUv[1]],
+        previousUv: [frame.view.previousJitterUv[0], frame.view.previousJitterUv[1]],
+      };
+    }
+    frame.history.commit();
+    this.lastSubmittedCoverage = frame.coverage;
+    if (frame.hasReactiveRevision) {
+      this.lastSubmittedReactiveRevision = frame.reactiveRevision;
+      this.hasSubmittedReactiveRevision = true;
+    }
+    this.lastFailure = undefined;
+    this.active = undefined;
+    frame.onSceneSubmitted?.(sceneDelta);
+  }
+
+  private abort(frame: ActiveTemporalFrame, stage: TemporalSubmitAbortStage): void {
+    if (this.active !== frame) return;
+    frame.history.abort();
+    this.lastFailure = { kind: 'submit-abort', stage };
+    this.active = undefined;
+  }
+}

package/src/temporal-inspection.ts

@@ -0,0 +1,194 @@
+import type { TextureFormat } from '@forgeax/engine-rhi';
+import type { TaaHistoryResetReason } from './taa-history-store';
+import {
+  TEMPORAL_MISSING_REASONS,
+  TEMPORAL_PRODUCER_LANES,
+  TEMPORAL_REACTIVE_REASONS,
+  type TemporalCoverageClass,
+  type TemporalMissingReason,
+  type TemporalProducerLane,
+  type TemporalReactiveReason,
+} from './temporal-coverage';
+import type {
+  TemporalFrameFailure,
+  TemporalFrameTransactionInspection,
+  TemporalHistoryDirection,
+} from './temporal-frame-transaction';
+
+export const TEMPORAL_INSPECTION_MISSING_ID_LIMIT = 32;
+
+export type TemporalInspectionStatus =
+  | 'off'
+  | 'first-frame'
+  | 'stable'
+  | 'reset'
+  | 'coverage-incomplete'
+  | 'capability-failure'
+  | 'pipeline-failure'
+  | 'submit-abort'
+  | 'device-recovery';
+
+export type TemporalInspectionRecovery =
+  | 'none'
+  | 'seed-history'
+  | 'enable-temporal-capabilities'
+  | 'fix-temporal-pipeline-topology'
+  | 'complete-temporal-coverage'
+  | 'retry-frame'
+  | 'rebuild-renderer';
+
+export interface TemporalInspectionCoverage {
+  readonly complete: boolean;
+  readonly exact: number;
+  readonly reactive: number;
+  readonly missing: number;
+  readonly missingContributorIds: readonly string[];
+  readonly omittedMissingContributorIds: number;
+  readonly lanes: readonly {
+    readonly lane: TemporalProducerLane;
+    readonly exact: number;
+    readonly reactive: number;
+    readonly missing: number;
+    readonly reactiveReasons: readonly {
+      readonly reason: TemporalReactiveReason;
+      readonly count: number;
+    }[];
+    readonly missingReasons: readonly {
+      readonly reason: TemporalMissingReason;
+      readonly count: number;
+    }[];
+  }[];
+}
+
+/** Bounded renderer-owned temporal POD. It never exposes graph or RHI handles. */
+export interface TemporalInspection {
+  readonly enabled: boolean;
+  readonly status: TemporalInspectionStatus;
+  readonly recovery: TemporalInspectionRecovery;
+  readonly active: boolean;
+  readonly viewId: string | undefined;
+  readonly temporalFrameIndex: number;
+  readonly historyVersion: number | undefined;
+  readonly historyValid: boolean;
+  readonly historyDirection: TemporalHistoryDirection;
+  readonly historyOwnerGeneration: number;
+  readonly historyFormat: TextureFormat | undefined;
+  readonly historyBytes: number;
+  readonly retiringGenerations: number;
+  readonly jitter:
+    | {
+        readonly currentUv: readonly [number, number];
+        readonly previousUv: readonly [number, number];
+      }
+    | undefined;
+  readonly resetReason: TaaHistoryResetReason | undefined;
+  readonly failure: TemporalFrameFailure | undefined;
+  readonly coverage: TemporalInspectionCoverage;
+  readonly environmentSignature: string | undefined;
+  readonly environmentResetCount: number;
+  readonly environmentPublishCount: number;
+}
+
+function statusOf(
+  source: TemporalFrameTransactionInspection,
+): readonly [TemporalInspectionStatus, TemporalInspectionRecovery] {
+  switch (source.lastFailure?.kind) {
+    case 'capability':
+      return ['capability-failure', 'enable-temporal-capabilities'];
+    case 'pipeline':
+      return ['pipeline-failure', 'fix-temporal-pipeline-topology'];
+    case 'submit-abort':
+      return ['submit-abort', 'retry-frame'];
+    case 'device-recovery':
+      return ['device-recovery', 'rebuild-renderer'];
+  }
+  if (!source.history.enabled) return ['off', 'none'];
+  if (!source.coverage.complete) return ['coverage-incomplete', 'complete-temporal-coverage'];
+  if (source.lastResetReason === 'device-recovery') {
+    return ['device-recovery', 'rebuild-renderer'];
+  }
+  if (source.lastResetReason === 'first-frame') return ['first-frame', 'seed-history'];
+  if (source.lastResetReason !== undefined) return ['reset', 'seed-history'];
+  return source.historyValid ? ['stable', 'none'] : ['first-frame', 'seed-history'];
+}
+
+export function projectTemporalInspection(
+  source: TemporalFrameTransactionInspection,
+): TemporalInspection {
+  const [status, recovery] = statusOf(source);
+  const missingContributorIds = Object.freeze(
+    source.coverage.missingContributors.slice(0, TEMPORAL_INSPECTION_MISSING_ID_LIMIT),
+  );
+  const countLane = (lane: TemporalProducerLane, coverage: TemporalCoverageClass): number =>
+    source.coverage.contributors.filter(
+      (contribution) => contribution.lane === lane && contribution.coverage === coverage,
+    ).length;
+  return {
+    enabled: source.history.enabled,
+    status,
+    recovery,
+    active: source.active,
+    viewId: source.lastSubmittedView?.viewId ?? source.history.viewId,
+    temporalFrameIndex: source.temporalFrameIndex,
+    historyVersion: source.lastSubmittedView?.historyVersion,
+    historyValid: source.historyValid,
+    historyDirection: source.historyDirection,
+    historyOwnerGeneration: source.history.ownerGeneration,
+    historyFormat: source.history.format,
+    historyBytes: source.history.historyBytes,
+    retiringGenerations: source.history.retiringGenerations,
+    jitter: source.lastJitter,
+    resetReason: source.lastResetReason,
+    failure: source.lastFailure,
+    coverage: {
+      complete: source.coverage.complete,
+      exact: source.coverage.exact,
+      reactive: source.coverage.reactive,
+      missing: source.coverage.missing,
+      missingContributorIds,
+      omittedMissingContributorIds: Math.max(
+        0,
+        source.coverage.missingContributors.length - missingContributorIds.length,
+      ),
+      lanes: Object.freeze(
+        TEMPORAL_PRODUCER_LANES.map((lane) =>
+          Object.freeze({
+            lane,
+            exact: countLane(lane, 'exact'),
+            reactive: countLane(lane, 'reactive'),
+            missing: countLane(lane, 'missing'),
+            reactiveReasons: Object.freeze(
+              TEMPORAL_REACTIVE_REASONS.map((reason) =>
+                Object.freeze({
+                  reason,
+                  count: source.coverage.contributors.filter(
+                    (contribution) =>
+                      contribution.lane === lane &&
+                      contribution.coverage === 'reactive' &&
+                      contribution.reason === reason,
+                  ).length,
+                }),
+              ),
+            ),
+            missingReasons: Object.freeze(
+              TEMPORAL_MISSING_REASONS.map((reason) =>
+                Object.freeze({
+                  reason,
+                  count: source.coverage.contributors.filter(
+                    (contribution) =>
+                      contribution.lane === lane &&
+                      contribution.coverage === 'missing' &&
+                      contribution.reason === reason,
+                  ).length,
+                }),
+              ),
+            ),
+          }),
+        ),
+      ),
+    },
+    environmentSignature: source.environmentSignature,
+    environmentResetCount: source.environmentResetCount ?? 0,
+    environmentPublishCount: source.environmentPublishCount ?? 0,
+  };
+}