@forgeax/engine-render 0.1.28 → 0.1.30

package/src/ssr/resources.ts

@@ -0,0 +1,202 @@
+import type {
+  GraphTexture,
+  GraphTextureView,
+  RenderGraphBuilder,
+  RenderGraphError,
+  RenderGraphFrame,
+} from '@forgeax/engine-render-graph';
+import { ok, type Result } from '@forgeax/engine-types';
+import { buildSsrHiZPlan, SSR_HIZ_FORMAT, type SsrHiZExtent, type SsrHiZPlan } from './hiz';
+
+export { SSR_HIZ_FORMAT } from './hiz';
+
+export const SSR_TRACE_FORMAT = 'rgba16float' as const;
+export const SSR_R32FLOAT_BYTES_PER_PIXEL = 4 as const;
+export const SSR_RGBA16FLOAT_BYTES_PER_PIXEL = 8 as const;
+export const SSR_TEMPORAL_PARAMS_BYTES = 32 as const;
+export const SSR_SPATIAL_MEMORY_BUDGET_BYTES = 45_088_768 as const;
+
+export interface SsrHiZResources {
+  readonly plan: SsrHiZPlan;
+  readonly texture: GraphTexture;
+  readonly levels: readonly GraphTextureView[];
+}
+
+export interface SsrSpatialTexture {
+  readonly texture: GraphTexture;
+  readonly view: GraphTextureView;
+  readonly width: number;
+  readonly height: number;
+  readonly format: typeof SSR_TRACE_FORMAT;
+}
+
+export interface SsrSpatialResources {
+  readonly hiz: SsrHiZResources;
+  readonly trace: SsrSpatialTexture;
+  /** Half-resolution reactivity of the admitted reflection source taps. */
+  readonly hitReactivity: GraphTextureView;
+  /** Half-resolution resolved radiance/confidence when temporal resolve is active. */
+  readonly resolved?: SsrSpatialTexture;
+  /** Sampled view of all resolved reflection levels; mip 0 remains sharp. */
+  readonly radiancePyramid?: GraphTextureView;
+}
+
+export interface SsrSpatialMemoryEstimate {
+  readonly width: number;
+  readonly height: number;
+  readonly halfWidth: number;
+  readonly halfHeight: number;
+  readonly hizBytes: number;
+  readonly traceBytes: number;
+  readonly hitReactivityBytes: number;
+  readonly resolvedBytes: number;
+  readonly historyBytes: number;
+  readonly temporalParamsBytes: number;
+  /** Full-resolution fallback output allocated only for SSR; included in the total. */
+  readonly fallbackInputBytes: number;
+  /** Total additional descriptor bytes, including the lighting-owned fallback, before aliasing. */
+  readonly ssrOwnedBytes: number;
+  readonly budgetBytes: typeof SSR_SPATIAL_MEMORY_BUDGET_BYTES;
+  readonly withinBudget: boolean;
+}
+
+function halfExtent(extent: SsrHiZExtent): SsrHiZExtent {
+  return {
+    width: Math.max(1, Math.floor(extent.width / 2)),
+    height: Math.max(1, Math.floor(extent.height / 2)),
+  };
+}
+
+function byteCount(width: number, height: number, bytesPerPixel: number): number {
+  const bytes = width * height * bytesPerPixel;
+  if (!Number.isSafeInteger(bytes)) {
+    throw new RangeError('SSR spatial descriptor byte count exceeds safe integer range');
+  }
+  return bytes;
+}
+
+/** Derive descriptor bytes for one admitted half-resolution SSR frame. */
+export function estimateSsrSpatialMemory(
+  extent: SsrHiZExtent,
+  options: { readonly temporal?: boolean } = {},
+): SsrSpatialMemoryEstimate {
+  const half = halfExtent(extent);
+  const plan = buildSsrHiZPlan(half);
+  const temporal = options.temporal !== false;
+  const hizBytes = plan.levels.reduce(
+    (sum, level) => sum + byteCount(level.width, level.height, SSR_R32FLOAT_BYTES_PER_PIXEL),
+    0,
+  );
+  const traceBytes = byteCount(half.width, half.height, SSR_RGBA16FLOAT_BYTES_PER_PIXEL);
+  const hitReactivityBytes = byteCount(half.width, half.height, SSR_R32FLOAT_BYTES_PER_PIXEL);
+  const resolvedBytes = temporal
+    ? plan.levels.reduce(
+        (sum, level) => sum + byteCount(level.width, level.height, SSR_RGBA16FLOAT_BYTES_PER_PIXEL),
+        0,
+      )
+    : 0;
+  const historyBytes = temporal ? half.width * half.height * 12 * 2 : 0;
+  const temporalParamsBytes = temporal ? SSR_TEMPORAL_PARAMS_BYTES : 0;
+  const fallbackInputBytes = byteCount(
+    extent.width,
+    extent.height,
+    SSR_RGBA16FLOAT_BYTES_PER_PIXEL,
+  );
+  const ssrOwnedBytes =
+    hizBytes +
+    traceBytes +
+    hitReactivityBytes +
+    resolvedBytes +
+    historyBytes +
+    temporalParamsBytes +
+    fallbackInputBytes;
+  return Object.freeze({
+    width: extent.width,
+    height: extent.height,
+    halfWidth: half.width,
+    halfHeight: half.height,
+    hizBytes,
+    traceBytes,
+    hitReactivityBytes,
+    resolvedBytes,
+    historyBytes,
+    temporalParamsBytes,
+    fallbackInputBytes,
+    ssrOwnedBytes,
+    budgetBytes: SSR_SPATIAL_MEMORY_BUDGET_BYTES,
+    withinBudget: ssrOwnedBytes <= SSR_SPATIAL_MEMORY_BUDGET_BYTES,
+  });
+}
+
+function texture(
+  graph: RenderGraphBuilder<RenderGraphFrame>,
+  label: string,
+  format: typeof SSR_TRACE_FORMAT,
+  extent: SsrHiZExtent,
+): Result<SsrSpatialTexture, RenderGraphError> {
+  const created = graph.createTexture(label, {
+    format,
+    size: { width: extent.width, height: extent.height },
+    domain: 'linear-hdr',
+  });
+  if (!created.ok) return created;
+  const view = graph.view(created.value, { label: `${label}.view`, dimension: '2d' });
+  if (!view.ok) return view;
+  return ok({
+    texture: created.value,
+    view: view.value,
+    width: extent.width,
+    height: extent.height,
+    format,
+  });
+}
+
+/** Create the renderer-owned Hi-Z texture and one typed view per mip. */
+export function createSsrHiZResources(
+  graph: RenderGraphBuilder<RenderGraphFrame>,
+  extent: SsrHiZExtent,
+): Result<SsrHiZResources, RenderGraphError> {
+  // Full-resolution depth already exists. Store only its reduced hierarchy.
+  const plan = buildSsrHiZPlan(halfExtent(extent));
+  const created = graph.createTexture('ssr-hiz', {
+    format: SSR_HIZ_FORMAT,
+    size: plan.graphSize,
+    mipLevelCount: plan.mipLevelCount,
+  });
+  if (!created.ok) return created;
+  const levels: GraphTextureView[] = [];
+  for (const entry of plan.levels) {
+    const view = graph.view(created.value, {
+      label: `ssr-hiz.mip-${entry.level}.view`,
+      dimension: '2d',
+      baseMipLevel: entry.level,
+      mipLevelCount: 1,
+    });
+    if (!view.ok) return view;
+    levels.push(view.value);
+  }
+  return ok({ plan, texture: created.value, levels: Object.freeze(levels) });
+}
+
+/** Allocate only the transient resources required by an admitted spatial path. */
+export function createSsrSpatialResources(
+  graph: RenderGraphBuilder<RenderGraphFrame>,
+  extent: SsrHiZExtent,
+): Result<SsrSpatialResources, RenderGraphError> {
+  const hiz = createSsrHiZResources(graph, extent);
+  if (!hiz.ok) return hiz;
+  const traceExtent = halfExtent(extent);
+  const trace = texture(graph, 'ssr-trace', SSR_TRACE_FORMAT, traceExtent);
+  if (!trace.ok) return trace;
+  const hitTexture = graph.createTexture('ssr-hit-reactivity', {
+    format: 'r32float',
+    size: traceExtent,
+  });
+  if (!hitTexture.ok) return hitTexture;
+  const hitReactivity = graph.view(hitTexture.value, {
+    label: 'ssr-hit-reactivity.view',
+    dimension: '2d',
+  });
+  if (!hitReactivity.ok) return hitReactivity;
+  return ok({ hiz: hiz.value, trace: trace.value, hitReactivity: hitReactivity.value });
+}

package/src/ssr/temporal.ts

@@ -0,0 +1,164 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type {
+  TemporalFrameBeginInput,
+  TemporalFrameCandidate,
+  TemporalFrameConsumerId,
+  TemporalFrameCoordinator,
+  TemporalFrameError,
+  TemporalFramePhases,
+  TemporalFrameReceipt,
+  TemporalFrameStage,
+} from '../temporal/frame-coordinator';
+import type {
+  SsrHistoryCandidate,
+  SsrHistoryError,
+  SsrHistoryFailureStage,
+  SsrHistoryInspection,
+  SsrHistoryOwner,
+  SsrHistoryResetReason,
+} from './history';
+
+export interface SsrTemporalCandidate<T> {
+  readonly temporal: TemporalFrameCandidate<T>;
+  readonly history: SsrHistoryCandidate;
+}
+export interface SsrTemporalExecutionError {
+  readonly code: 'ssr-temporal-stage-failed';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: Readonly<{ readonly stage: TemporalFrameStage; readonly cause: unknown }>;
+}
+export interface SsrTemporalInspection {
+  readonly sharedEpoch: number;
+  readonly consumerIds: readonly TemporalFrameConsumerId[];
+  readonly coordinatorAttempt: 'none' | 'active' | 'committed' | 'aborted';
+  readonly history: SsrHistoryInspection;
+}
+export type SsrTemporalError = TemporalFrameError | SsrHistoryError | SsrTemporalExecutionError;
+
+function stageFromError(cause: unknown): TemporalFrameStage {
+  if (typeof cause === 'object' && cause !== null && 'stage' in cause) {
+    const stage = (cause as { readonly stage?: unknown }).stage;
+    if (stage === 'build' || stage === 'encode' || stage === 'finish' || stage === 'submit') {
+      return stage;
+    }
+  }
+  return 'submit';
+}
+function coordinatorInput<T>(input: TemporalFrameBeginInput<T>): TemporalFrameBeginInput<T> {
+  const consumerIds = input.consumerIds?.includes('ssr')
+    ? input.consumerIds
+    : [...(input.consumerIds ?? []), 'ssr' as const];
+  return { ...input, temporalDemand: true, consumerIds };
+}
+function resetCoordinator<T>(
+  coordinator: TemporalFrameCoordinator<T>,
+  reason: SsrHistoryResetReason,
+): void {
+  switch (reason) {
+    case 'first-enable':
+    case 'disable':
+      return;
+    case 'resize':
+      coordinator.reset('resize');
+      return;
+    case 'camera-cut':
+      coordinator.reset('cut');
+      return;
+    case 'history-version':
+      coordinator.reset('camera-switch');
+      return;
+    case 'coverage-loss':
+      coordinator.reset('detach');
+      return;
+    case 'reflection-generation':
+    case 'device-recovery':
+      coordinator.reset('device-generation');
+      return;
+  }
+}
+
+/** Stages SSR history beside the shared renderer transaction without owning submit or epochs. */
+export class SsrTemporalConsumer<T = unknown> {
+  constructor(
+    private readonly coordinator: TemporalFrameCoordinator<T>,
+    readonly history: SsrHistoryOwner,
+  ) {}
+  begin(
+    input: TemporalFrameBeginInput<T>,
+  ): Result<SsrTemporalCandidate<T>, TemporalFrameError | SsrHistoryError> {
+    const history = this.history.beginFrame();
+    if (!history.ok) return history;
+    const temporal = this.coordinator.begin(coordinatorInput(input));
+    if (!temporal.ok) {
+      this.history.abortFrame(history.value, 'build');
+      return temporal;
+    }
+    return ok({ temporal: temporal.value, history: history.value });
+  }
+  commit(
+    candidate: SsrTemporalCandidate<T>,
+  ): Result<TemporalFrameReceipt<T>, TemporalFrameError | SsrHistoryError> {
+    const committed = this.coordinator.commit(candidate.temporal);
+    if (!committed.ok) {
+      this.history.abortFrame(candidate.history, 'submit');
+      return committed;
+    }
+    const history = this.history.commitFrame(candidate.history);
+    if (!history.ok) return history;
+    return committed;
+  }
+  abort(candidate: SsrTemporalCandidate<T>, stage: SsrHistoryFailureStage): void {
+    this.history.abortFrame(candidate.history, stage);
+    this.coordinator.abort(candidate.temporal, stage);
+  }
+  run(
+    input: TemporalFrameBeginInput<T>,
+    phases: TemporalFramePhases<T>,
+  ): Result<TemporalFrameReceipt<T>, SsrTemporalError> {
+    const started = this.begin(input);
+    if (!started.ok) return started;
+    const candidate = started.value;
+    try {
+      const built = phases.build();
+      phases.encode(built);
+      phases.finish();
+      phases.submit();
+    } catch (cause) {
+      const stage = stageFromError(cause);
+      this.abort(candidate, stage);
+      return err({
+        code: 'ssr-temporal-stage-failed',
+        expected: `SSR temporal ${stage} succeeds before commit`,
+        hint: 'inspect the owned stage failure and retry without promoting the candidate',
+        detail: { stage, cause },
+      });
+    }
+    return this.commit(candidate);
+  }
+  reset(reason: SsrHistoryResetReason): void {
+    this.history.reset(reason);
+    resetCoordinator(this.coordinator, reason);
+  }
+  retireAfterFence(
+    queue: Parameters<SsrHistoryOwner['retireAfterFence']>[0],
+    onFailure: Parameters<SsrHistoryOwner['retireAfterFence']>[1],
+  ): void {
+    this.history.retireAfterFence(queue, onFailure);
+  }
+  inspect(): SsrTemporalInspection {
+    const temporal = this.coordinator.inspect();
+    return Object.freeze({
+      sharedEpoch: temporal.epoch,
+      consumerIds: temporal.consumerIds,
+      coordinatorAttempt: temporal.attempt,
+      history: this.history.inspect(),
+    });
+  }
+}
+export function createSsrTemporalConsumer<T>(
+  coordinator: TemporalFrameCoordinator<T>,
+  history: SsrHistoryOwner,
+): SsrTemporalConsumer<T> {
+  return new SsrTemporalConsumer(coordinator, history);
+}