@forgeax/engine-render 0.1.7 → 0.1.19

package/src/temporal/inspection.ts

@@ -0,0 +1,97 @@
+import type { TemporalGpuState } from './gpu';
+import type { TemporalHistory } from './history';
+import type { TemporalView } from './view';
+
+export interface TemporalResourceInspection {
+  readonly active: number;
+  readonly candidate: number;
+  readonly retiring: number;
+  readonly activeBytes: number;
+  readonly candidateBytes: number;
+  readonly retiringBytes: number;
+}
+
+export interface TemporalInspection {
+  readonly mode: 'none' | 'fxaa' | 'msaa' | 'taa';
+  /** Compatibility projection for temporal carriers; derived from this snapshot. */
+  readonly status: 'off' | 'first-frame' | 'stable' | 'reset' | 'aborted';
+  readonly historyAttempt: 'none' | 'active' | 'committed' | 'aborted';
+  readonly epoch: number;
+  readonly viewIdentity: string;
+  readonly historyValid: boolean;
+  readonly resetReason: string | undefined;
+  readonly frameIndex: number;
+  readonly historyBytes: number;
+  readonly coverage: { readonly width: number; readonly height: number };
+  readonly deviceGeneration: number;
+  readonly resources: TemporalResourceInspection;
+}
+
+function gpuBytes(state: TemporalGpuState | undefined): number {
+  return state === undefined ? 0 : state.width * state.height * 32;
+}
+
+function gpuResources(state: TemporalGpuState | undefined): number {
+  return state?.childScope.resourceDelta() ?? 0;
+}
+
+export function inspectTemporal(
+  view: TemporalView | undefined,
+  history: TemporalHistory | undefined,
+  options: {
+    readonly active?: TemporalGpuState;
+    readonly candidate?: TemporalGpuState;
+    readonly retiring?: readonly TemporalGpuState[];
+    readonly deviceGeneration?: number;
+  } = {},
+): TemporalInspection {
+  const snapshot = history?.snapshot();
+  const mode = view?.input.antialias ?? 'none';
+  const taa = mode === 'taa';
+  const active = taa ? options.active : undefined;
+  const candidate = taa ? options.candidate : undefined;
+  const retiring = taa ? (options.retiring ?? []) : [];
+  const historyBytes = active === undefined ? (snapshot?.coverage.bytes ?? 0) : gpuBytes(active);
+  const coverage = snapshot?.coverage ?? {
+    width: active?.width ?? candidate?.width ?? 0,
+    height: active?.height ?? candidate?.height ?? 0,
+  };
+  const retiringCount = retiring.reduce((count, state) => count + gpuResources(state), 0);
+  const retiringBytes = retiring.reduce((bytes, state) => bytes + gpuBytes(state), 0);
+  const status =
+    mode !== 'taa'
+      ? 'off'
+      : view?.resetReason !== undefined && view.resetReason !== 'first-frame'
+        ? 'reset'
+        : view?.historyValid === true || snapshot?.historyValid === true
+          ? 'stable'
+          : 'first-frame';
+  const historyAttempt =
+    mode !== 'taa'
+      ? 'none'
+      : (active?.valid ?? snapshot?.historyValid ?? false)
+        ? 'committed'
+        : 'active';
+  return Object.freeze({
+    mode,
+    status,
+    historyAttempt,
+    epoch: view?.input.frameIndex ?? snapshot?.frameIndex ?? 0,
+    viewIdentity: view?.input.viewIdentity ?? 'camera:default',
+    historyValid: active?.valid ?? snapshot?.historyValid ?? false,
+    resetReason: view?.resetReason ?? snapshot?.resetReason,
+    frameIndex: view?.temporalFrameIndex ?? snapshot?.frameIndex ?? 0,
+    historyBytes,
+    coverage: Object.freeze({ width: coverage.width, height: coverage.height }),
+    deviceGeneration:
+      options.deviceGeneration ?? active?.scope.generation ?? candidate?.scope.generation ?? 0,
+    resources: Object.freeze({
+      active: gpuResources(active),
+      candidate: gpuResources(candidate),
+      retiring: retiringCount,
+      activeBytes: gpuBytes(active),
+      candidateBytes: gpuBytes(candidate),
+      retiringBytes,
+    }),
+  });
+}

package/src/temporal/scene-data-catalog.ts

@@ -0,0 +1,200 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { RenderError } from '../errors/render';
+import { SceneDataUnavailableError } from '../errors/render';
+import {
+  registerSceneDataTarget,
+  SCENE_DATA_TEMPORAL_V1_DESCRIPTOR,
+  SCENE_DATA_TEMPORAL_V1_SCHEMA,
+  type SceneDataLane,
+  type SceneDataSchemaId,
+  type SceneDataTarget,
+  sceneDataTargetOwner,
+  sceneDataTokenMismatch,
+} from './scene-data';
+
+export type SceneDataAvailability =
+  | {
+      readonly status: 'available';
+      readonly completeness: 'exact' | 'exact-with-reactive-fallback';
+    }
+  | {
+      readonly status: 'unavailable';
+      readonly reason:
+        | 'capability-missing'
+        | 'producer-missing'
+        | 'coverage-incomplete'
+        | 'renderer-recovering';
+    };
+
+export interface SceneDataInspection {
+  readonly schema: SceneDataSchemaId;
+  readonly status: SceneDataAvailability['status'];
+  readonly generation: number;
+  readonly planIdentity: string;
+  readonly lane: SceneDataLane;
+  readonly completeness?: 'exact' | 'exact-with-reactive-fallback';
+  readonly reason?: Exclude<SceneDataAvailability, { status: 'available' }>['reason'];
+  readonly missingContributorIds: readonly string[];
+  readonly omittedMissingContributorCount: number;
+}
+
+export interface SceneDataCatalogOptions {
+  readonly featureIdentity: string;
+  readonly generation: number;
+  readonly planIdentity: string;
+  readonly lane?: SceneDataLane;
+  readonly rgba16floatRenderable: boolean;
+  readonly producerPresent?: boolean;
+  readonly coverageComplete?: boolean;
+  readonly recovering?: boolean;
+  readonly reactiveFallback?: boolean;
+  readonly missingContributorIds?: readonly string[];
+}
+
+export interface SceneDataCatalog {
+  readonly schema: typeof SCENE_DATA_TEMPORAL_V1_SCHEMA;
+  readonly generation: number;
+  readonly planIdentity: string;
+  readonly availability: SceneDataAvailability;
+  require<Schema extends SceneDataSchemaId>(schema: Schema): SceneDataTarget<Schema>;
+  validate(target: SceneDataTarget, generation?: number): Result<SceneDataTarget, RenderError>;
+  inspect(): SceneDataInspection;
+}
+
+function availability(options: SceneDataCatalogOptions): SceneDataAvailability {
+  if (options.recovering) return { status: 'unavailable', reason: 'renderer-recovering' };
+  if (!options.rgba16floatRenderable)
+    return { status: 'unavailable', reason: 'capability-missing' };
+  if (options.producerPresent === false)
+    return { status: 'unavailable', reason: 'producer-missing' };
+  if (options.coverageComplete === false)
+    return { status: 'unavailable', reason: 'coverage-incomplete' };
+  return {
+    status: 'available',
+    completeness: options.reactiveFallback ? 'exact-with-reactive-fallback' : 'exact',
+  };
+}
+
+function createTarget(owner: SceneDataCatalogOptions): SceneDataTarget {
+  const target = Object.freeze({
+    kind: 'scene-data' as const,
+    schema: SCENE_DATA_TEMPORAL_V1_SCHEMA,
+    access: 'sampled-read' as const,
+    format: 'rgba16float' as const,
+    sampleCount: 1 as const,
+    extent: 'render-resolution' as const,
+  }) as SceneDataTarget;
+  registerSceneDataTarget(target, {
+    featureIdentity: owner.featureIdentity,
+    planIdentity: owner.planIdentity,
+    generation: owner.generation,
+  });
+  return target;
+}
+
+function tokenError(catalog: SceneDataCatalogOptions, operation: string): RenderError {
+  return sceneDataTokenMismatch(
+    operation,
+    'foreign-kind',
+    {
+      featureIdentity: catalog.featureIdentity,
+      planIdentity: catalog.planIdentity,
+      generation: catalog.generation,
+    },
+    undefined,
+  );
+}
+
+function unavailableError(
+  options: SceneDataCatalogOptions,
+  reason: Exclude<SceneDataAvailability, { status: 'available' }>['reason'],
+): RenderError {
+  const recovery =
+    reason === 'capability-missing'
+      ? 'enable-capability'
+      : reason === 'renderer-recovering'
+        ? 'renderer-recover'
+        : 'next-frame';
+  return new SceneDataUnavailableError({
+    featureIdentity: options.featureIdentity,
+    schema: SCENE_DATA_TEMPORAL_V1_SCHEMA,
+    lane: options.lane ?? 'direct',
+    reason,
+    missingContributorIds: options.missingContributorIds ?? [],
+    omittedMissingContributorCount: 0,
+    recovery,
+  });
+}
+
+export function createSceneDataCatalog(options: SceneDataCatalogOptions): SceneDataCatalog {
+  const state = availability(options);
+  const owner = {
+    featureIdentity: options.featureIdentity,
+    planIdentity: options.planIdentity,
+    generation: options.generation,
+  };
+  const missing = [...(options.missingContributorIds ?? [])];
+  const inspectionBase = {
+    schema: SCENE_DATA_TEMPORAL_V1_SCHEMA,
+    generation: options.generation,
+    planIdentity: options.planIdentity,
+    lane: options.lane ?? 'direct',
+    missingContributorIds: Object.freeze(missing.slice(0, 32)),
+    omittedMissingContributorCount: Math.max(0, missing.length - 32),
+  };
+  return {
+    schema: SCENE_DATA_TEMPORAL_V1_SCHEMA,
+    generation: options.generation,
+    planIdentity: options.planIdentity,
+    availability: state,
+    require(schema) {
+      if (schema !== SCENE_DATA_TEMPORAL_V1_SCHEMA || state.status !== 'available') {
+        if (state.status === 'unavailable') throw unavailableError(options, state.reason);
+        throw tokenError(options, 'require scene-data target');
+      }
+      return createTarget(options) as SceneDataTarget<typeof schema>;
+    },
+    validate(target, generation = options.generation) {
+      const targetOwner = sceneDataTargetOwner(target);
+      if (targetOwner === undefined) {
+        return err(
+          sceneDataTokenMismatch('validate scene-data target', 'foreign-feature', owner, target),
+        );
+      }
+      if (
+        targetOwner.planIdentity !== owner.planIdentity ||
+        targetOwner.featureIdentity !== owner.featureIdentity
+      ) {
+        return err(
+          sceneDataTokenMismatch('validate scene-data target', 'foreign-feature', owner, target),
+        );
+      }
+      if (generation !== owner.generation || targetOwner.generation !== owner.generation) {
+        return err(
+          sceneDataTokenMismatch(
+            'validate scene-data target',
+            'generation-mismatch',
+            owner,
+            target,
+          ),
+        );
+      }
+      if (target.access !== 'sampled-read') {
+        return err(
+          sceneDataTokenMismatch('validate scene-data target', 'layout-mismatch', owner, target),
+        );
+      }
+      return ok(target);
+    },
+    inspect() {
+      return Object.freeze(
+        state.status === 'available'
+          ? { ...inspectionBase, status: state.status, completeness: state.completeness }
+          : { ...inspectionBase, status: state.status, reason: state.reason },
+      );
+    },
+  };
+}
+
+export { SCENE_DATA_TEMPORAL_V1_SCHEMA } from './scene-data';
+export { SCENE_DATA_TEMPORAL_V1_DESCRIPTOR };

package/src/temporal/scene-data.ts

@@ -0,0 +1,149 @@
+import { type RenderError, RenderFeaturePreparedStateMismatchError } from '../errors/render';
+import type { RenderFeatureTargetHandle } from '../features/targets';
+
+/** The closed semantic schema namespace published by the render owner. */
+export const SCENE_DATA_TEMPORAL_V1_SCHEMA = 'forgeax::scene-data::temporal-v1' as const;
+export type SceneDataSchemaId = typeof SCENE_DATA_TEMPORAL_V1_SCHEMA;
+
+export type SceneDataLane = 'direct' | 'clustered' | 'cpu-webgl2';
+
+export interface SceneDataTemporalV1Descriptor {
+  readonly schema: typeof SCENE_DATA_TEMPORAL_V1_SCHEMA;
+  readonly format: 'rgba16float';
+  readonly sampleCount: 1;
+  readonly extent: 'render-resolution';
+  readonly clearValue: readonly [0, 0, -1, 1];
+  readonly channels: Readonly<{
+    readonly motionUv: 'rg';
+    readonly viewDepth: 'b-log2-1-plus-depth';
+    readonly reactive: 'a';
+  }>;
+}
+
+export const SCENE_DATA_TEMPORAL_V1_DESCRIPTOR: SceneDataTemporalV1Descriptor = Object.freeze({
+  schema: SCENE_DATA_TEMPORAL_V1_SCHEMA,
+  format: 'rgba16float',
+  sampleCount: 1,
+  extent: 'render-resolution',
+  clearValue: [0, 0, -1, 1] as const,
+  channels: Object.freeze({
+    motionUv: 'rg',
+    viewDepth: 'b-log2-1-plus-depth',
+    reactive: 'a',
+  }),
+});
+
+/** Opaque, sampled-read-only semantic data token. */
+export interface SceneDataTarget<Schema extends SceneDataSchemaId = SceneDataSchemaId> {
+  readonly kind: 'scene-data';
+  readonly schema: Schema;
+  readonly access: 'sampled-read';
+  readonly format: 'rgba16float';
+  readonly sampleCount: 1;
+  readonly extent: 'render-resolution';
+  readonly __sceneDataTarget: unique symbol;
+}
+
+export type SceneDataTokenMismatch = RenderFeaturePreparedStateMismatchError;
+
+const targetOwners = new WeakMap<object, SceneDataCatalogIdentity>();
+
+export interface SceneDataCatalogIdentity {
+  readonly featureIdentity: string;
+  readonly planIdentity: string;
+  readonly generation: number;
+}
+
+export function registerSceneDataTarget(
+  target: SceneDataTarget,
+  owner: SceneDataCatalogIdentity,
+): void {
+  targetOwners.set(target, owner);
+}
+
+export function sceneDataTargetOwner(
+  target: SceneDataTarget,
+): SceneDataCatalogIdentity | undefined {
+  return typeof target === 'object' && target !== null ? targetOwners.get(target) : undefined;
+}
+
+export function sceneDataTokenMismatch(
+  operation: string,
+  reason: 'foreign-feature' | 'foreign-kind' | 'generation-mismatch' | 'layout-mismatch',
+  owner: SceneDataCatalogIdentity,
+  target: Partial<SceneDataTarget> | undefined,
+): SceneDataTokenMismatch {
+  const detail =
+    reason === 'generation-mismatch'
+      ? {
+          featureIdentity: owner.featureIdentity,
+          order: -1,
+          stage: 'contribute' as const,
+          operation,
+          resourceKind: 'attachment' as const,
+          reason,
+          expectedGeneration: owner.generation,
+          actualGeneration: targetOwners.get(target as object)?.generation ?? -1,
+          recovery: 'renderer-recover' as const,
+        }
+      : reason === 'foreign-feature'
+        ? {
+            featureIdentity: owner.featureIdentity,
+            order: -1,
+            stage: 'contribute' as const,
+            operation,
+            resourceKind: 'attachment' as const,
+            reason,
+            expectedFeatureIdentity: owner.featureIdentity,
+            actualFeatureIdentity: targetOwners.get(target as object)?.featureIdentity ?? 'unknown',
+            recovery: 'next-frame' as const,
+          }
+        : reason === 'foreign-kind'
+          ? {
+              featureIdentity: owner.featureIdentity,
+              order: -1,
+              stage: 'contribute' as const,
+              operation,
+              resourceKind: 'attachment' as const,
+              reason,
+              expectedKind: 'attachment' as const,
+              actualKind: 'pipeline' as const,
+              recovery: 'next-frame' as const,
+            }
+          : {
+              featureIdentity: owner.featureIdentity,
+              order: -1,
+              stage: 'contribute' as const,
+              operation,
+              resourceKind: 'attachment' as const,
+              reason,
+              expectedLayout: 'sampled-read-temporal-v1',
+              actualLayout: target?.access ?? 'unknown',
+              recovery: 'next-frame' as const,
+            };
+  return new RenderFeaturePreparedStateMismatchError(detail);
+}
+
+export function isSceneDataTarget(value: unknown): value is SceneDataTarget {
+  if (value === null || typeof value !== 'object') return false;
+  const candidate = value as Partial<SceneDataTarget>;
+  return (
+    candidate.kind === 'scene-data' &&
+    candidate.schema === SCENE_DATA_TEMPORAL_V1_SCHEMA &&
+    candidate.access === 'sampled-read' &&
+    candidate.format === 'rgba16float' &&
+    candidate.sampleCount === 1 &&
+    candidate.extent === 'render-resolution' &&
+    targetOwners.has(value)
+  );
+}
+
+export function sceneDataTargetAsAttachment(_target: SceneDataTarget): never {
+  throw new TypeError('SceneDataTarget is sampled-read-only and cannot be used as an attachment');
+}
+
+export type SceneDataTargetInput = RenderFeatureTargetHandle | SceneDataTarget;
+
+export function sceneDataError(error: SceneDataTokenMismatch): RenderError {
+  return error;
+}

package/src/temporal/standard-scene-data.ts

@@ -0,0 +1,182 @@
+import type {
+  GraphTextureDescriptor,
+  RenderGraphBuilder,
+  RenderGraphError,
+} from '@forgeax/engine-render-graph';
+import { ok, type Result } from '@forgeax/engine-types';
+import type { RenderPipelineFrame, RenderPipelineTarget } from '../render-pipeline';
+import { createRenderPipelineTarget } from '../render-pipeline';
+import { addTypedFullscreenPass, addTypedScenePass } from '../typed-render-graph-primitives';
+
+export interface StandardTemporalDemandInput {
+  readonly taa: boolean;
+  readonly motionBlur: boolean;
+}
+
+export interface StandardTemporalDemand {
+  readonly consumerIds: readonly ('taa' | 'motion-blur')[];
+  readonly targetCount: 0 | 1;
+  readonly producerPassCount: 0 | 1;
+  readonly historyCount: 0 | 1;
+}
+
+export interface StandardTemporalDemandDescription {
+  readonly consumerCount: number;
+  readonly targetCount: 0 | 1;
+  readonly producerPassCount: 0 | 1;
+  readonly historyCount: 0 | 1;
+  readonly byteLength: 0 | 1;
+}
+
+/** Aggregate all temporal consumers before any graph resource is allocated. */
+export function aggregateTemporalDemand(
+  input: StandardTemporalDemandInput,
+): StandardTemporalDemand {
+  const consumerIds = [
+    ...(input.taa ? (['taa'] as const) : []),
+    ...(input.motionBlur ? (['motion-blur'] as const) : []),
+  ];
+  const requested = consumerIds.length > 0;
+  return Object.freeze({
+    consumerIds: Object.freeze(consumerIds),
+    targetCount: requested ? 1 : 0,
+    producerPassCount: requested ? 1 : 0,
+    historyCount: input.taa ? 1 : 0,
+  });
+}
+
+export function describeTemporalDemand(
+  demand: StandardTemporalDemand,
+): StandardTemporalDemandDescription {
+  return {
+    consumerCount: demand.consumerIds.length,
+    targetCount: demand.targetCount,
+    producerPassCount: demand.producerPassCount,
+    historyCount: demand.historyCount,
+    byteLength: demand.targetCount,
+  };
+}
+
+export type StandardTemporalLane = 'direct' | 'clustered' | 'cpu-webgl2' | 'rhi-null';
+
+export type StandardTemporalLaneAdmission =
+  | {
+      readonly status: 'available';
+      readonly schema: typeof import('./scene-data').SCENE_DATA_TEMPORAL_V1_SCHEMA;
+      readonly producerId: 'forgeax::standard::scene-data';
+      readonly structuralOnly: boolean;
+      readonly format: 'rgba16float';
+    }
+  | {
+      readonly status: 'unavailable';
+      readonly reason: 'capability-missing' | 'producer-missing' | 'no-demand';
+      readonly format?: never;
+    };
+
+export function standardTemporalLaneAdmission(input: {
+  readonly lane: StandardTemporalLane;
+  readonly demand: StandardTemporalDemand;
+  readonly capabilities: {
+    readonly compute: boolean;
+    readonly storageBuffer: boolean;
+    readonly rgba16floatRenderable: boolean;
+    readonly filterable?: boolean;
+    readonly copy?: boolean;
+    readonly readback?: boolean;
+    readonly producerPresent?: boolean;
+  };
+}): StandardTemporalLaneAdmission {
+  if (input.demand.targetCount === 0) return { status: 'unavailable', reason: 'no-demand' };
+  if (input.capabilities.producerPresent === false)
+    return { status: 'unavailable', reason: 'producer-missing' };
+  if (
+    !input.capabilities.rgba16floatRenderable ||
+    input.capabilities.filterable === false ||
+    input.capabilities.copy === false ||
+    input.capabilities.readback === false
+  ) {
+    return { status: 'unavailable', reason: 'capability-missing' };
+  }
+  return {
+    status: 'available',
+    schema: 'forgeax::scene-data::temporal-v1',
+    producerId: 'forgeax::standard::scene-data',
+    structuralOnly: input.lane === 'rhi-null',
+    format: 'rgba16float',
+  };
+}
+
+export function standardTemporalPostOrder(input: {
+  readonly taa: boolean;
+  readonly motionBlur: boolean;
+  readonly bloom: boolean;
+}): readonly string[] {
+  const order = ['scene'];
+  if (input.taa || input.motionBlur) order.push('standard-scene-data');
+  if (input.taa) order.push('taa-resolve');
+  if (input.motionBlur) order.push('motion-blur');
+  if (input.bloom) order.push('bloom', 'tone');
+  order.push('output');
+  return Object.freeze(order);
+}
+
+export interface StandardSceneDataTargets {
+  readonly temporal: RenderPipelineTarget;
+}
+
+const TEMPORAL_TARGET: GraphTextureDescriptor = {
+  format: 'rgba16float',
+  size: 'surface',
+  sampleCount: 1,
+};
+
+/** The single Standard TAA current-frame producer target. */
+export function createStandardSceneDataTarget(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+): Result<StandardSceneDataTargets, RenderGraphError> {
+  const temporal = createRenderPipelineTarget(graph, 'standard-scene-temporal', TEMPORAL_TARGET);
+  return temporal.ok ? ok({ temporal: temporal.value }) : temporal;
+}
+
+export function addStandardSceneDataPass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  target: RenderPipelineTarget,
+  depth: RenderPipelineTarget,
+): Result<void, RenderGraphError> {
+  return addTypedScenePass(graph, {
+    name: 'standard-scene-data',
+    color: target,
+    depth,
+    selector: { LightMode: ['Deferred', 'Forward'] },
+    passKind: 'temporal',
+    // The temporal producer re-rasterizes the current scene after the main
+    // color pass has populated depth. Its output is a semantic motion target;
+    // it must cover the same fragments even when TAA jitter moves the raster
+    // edge by a subpixel, while the loaded scene depth remains the consumer's
+    // depth-rejection source for Motion Blur/TAA.
+    clearColor: [0, 0, -1, 1],
+    colorLoadOp: 'clear',
+    depthLoadOp: 'load',
+  });
+}
+
+export function addTaaResolvePass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  current: RenderPipelineTarget,
+  currentTemporal: RenderPipelineTarget,
+  previousColor: RenderPipelineTarget,
+  previousTemporal: RenderPipelineTarget,
+  output: RenderPipelineTarget,
+): Result<void, RenderGraphError> {
+  return addTypedFullscreenPass(graph, {
+    name: 'taa-resolve',
+    shader: 'forgeax.taa-resolve',
+    input: current,
+    output,
+    additionalReads: [
+      { key: 'scene-temporal', target: currentTemporal },
+      { key: 'taa-history-color', target: previousColor },
+      { key: 'taa-history-temporal', target: previousTemporal },
+    ],
+  });
+}