@forgeax/engine-render 0.1.4 → 0.1.6

package/src/temporal-coverage.ts

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

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

@@ -1,194 +0,0 @@
-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,
-  };
-}