@forgeax/engine-render 0.1.7 → 0.1.20

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

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