@forgeax/engine-render 0.1.7 → 0.1.20

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';

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