@forgeax/engine-render 0.1.27 → 0.1.29

package/src/pipeline/standard-output/lut-state.ts

@@ -0,0 +1,176 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+
+export type StandardLutResetReason = 'device-recovered' | 'resource-removed' | 'validation-failed';
+
+export type StandardLutStateErrorCode =
+  | 'standard-lut-stale-generation'
+  | 'standard-lut-invalid-resident';
+
+export interface StandardLutStateError {
+  readonly code: StandardLutStateErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: Readonly<Record<string, number | string>>;
+}
+
+/** Bounded preparation failure retained for recovery and detached inspection. */
+export interface StandardLutFailure {
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: Readonly<Record<string, number | string | boolean>>;
+}
+
+export interface StandardLutState {
+  readonly resident: string | null;
+  readonly lastKnownGood: string | null;
+  readonly sourceKey: string | null;
+  readonly targetGeneration: number;
+  readonly deviceEpoch: number;
+  readonly recentFailure?: StandardLutFailure;
+  readonly reset: readonly StandardLutResetReason[];
+  readonly receipt: Readonly<{ frameId: number; committed: boolean }>;
+}
+
+export interface StandardLutCandidate {
+  readonly resident: string;
+  readonly sourceKey?: string;
+  readonly generation: number;
+  readonly deviceEpoch: number;
+  readonly frameId: number;
+}
+
+export function createStandardLutState(
+  input: {
+    readonly resident?: string | null;
+    readonly targetGeneration?: number;
+    readonly deviceEpoch?: number;
+    readonly frameId?: number;
+  } = {},
+): StandardLutState {
+  const resident = input.resident ?? null;
+  const targetGeneration = input.targetGeneration ?? 0;
+  const deviceEpoch = input.deviceEpoch ?? 0;
+  return Object.freeze({
+    resident,
+    lastKnownGood: resident,
+    sourceKey: resident,
+    targetGeneration,
+    deviceEpoch,
+    reset: Object.freeze([]),
+    receipt: Object.freeze({ frameId: input.frameId ?? 0, committed: false }),
+  });
+}
+
+export function prepareStandardLutCandidate(
+  state: StandardLutState,
+  candidate: StandardLutCandidate,
+): Result<StandardLutCandidate, StandardLutStateError> {
+  if (candidate.resident.length === 0) {
+    return err({
+      code: 'standard-lut-invalid-resident',
+      expected: 'a non-empty resident LUT identity',
+      hint: 'retain the existing compatible LUT and rebuild the candidate',
+      detail: { resident: candidate.resident },
+    });
+  }
+  if (
+    candidate.generation !== state.targetGeneration ||
+    candidate.deviceEpoch !== state.deviceEpoch
+  ) {
+    return err({
+      code: 'standard-lut-stale-generation',
+      expected: `generation ${state.targetGeneration} at device epoch ${state.deviceEpoch}`,
+      hint: 'discard the late candidate and rebuild from the active device scope',
+      detail: {
+        expectedGeneration: state.targetGeneration,
+        actualGeneration: candidate.generation,
+        expectedDeviceEpoch: state.deviceEpoch,
+        actualDeviceEpoch: candidate.deviceEpoch,
+      },
+    });
+  }
+  return ok(Object.freeze({ ...candidate }));
+}
+
+/** Publish LUT residency only after the owning frame has submitted. */
+export function commitStandardLutCandidate(
+  state: StandardLutState,
+  candidate: StandardLutCandidate,
+): StandardLutState {
+  const { recentFailure: _recentFailure, ...withoutFailure } = state;
+  return Object.freeze({
+    ...withoutFailure,
+    resident: candidate.resident,
+    lastKnownGood: candidate.resident,
+    sourceKey: candidate.sourceKey ?? candidate.resident,
+    receipt: Object.freeze({ frameId: candidate.frameId, committed: true }),
+  });
+}
+
+/** Keep the accepted/LKG resource while recording a failed replacement. */
+export function recordStandardLutFailure(
+  state: StandardLutState,
+  failure: StandardLutFailure,
+): StandardLutState {
+  return Object.freeze({
+    ...state,
+    recentFailure: Object.freeze({
+      ...failure,
+      detail: Object.freeze({ ...failure.detail }),
+    }),
+  });
+}
+
+/** Detached, bounded LUT facts for renderer inspection. */
+export interface StandardLutInspection {
+  readonly resident: string | null;
+  readonly lastKnownGood: string | null;
+  readonly sourceKey: string | null;
+  readonly targetGeneration: number;
+  readonly deviceEpoch: number;
+  readonly recentFailure?: StandardLutFailure;
+  readonly reset: readonly StandardLutResetReason[];
+  readonly receipt: Readonly<{ frameId: number; committed: boolean }>;
+}
+
+export function inspectStandardLutState(state: StandardLutState): Readonly<StandardLutInspection> {
+  return Object.freeze({
+    resident: state.resident,
+    lastKnownGood: state.lastKnownGood,
+    sourceKey: state.sourceKey,
+    targetGeneration: state.targetGeneration,
+    deviceEpoch: state.deviceEpoch,
+    ...(state.recentFailure === undefined
+      ? {}
+      : {
+          recentFailure: Object.freeze({
+            ...state.recentFailure,
+            detail: Object.freeze({ ...state.recentFailure.detail }),
+          }),
+        }),
+    reset: Object.freeze([...state.reset]),
+    receipt: Object.freeze({ ...state.receipt }),
+  });
+}
+
+/** Retire device-bound residency while retaining the compatible LKG identity. */
+export function resetStandardLutState(
+  state: StandardLutState,
+  reason: StandardLutResetReason,
+  input: { readonly targetGeneration: number; readonly deviceEpoch: number },
+): StandardLutState {
+  const recentFailure = state.recentFailure;
+  return Object.freeze({
+    ...state,
+    resident: null,
+    sourceKey: null,
+    targetGeneration: input.targetGeneration,
+    deviceEpoch: input.deviceEpoch,
+    // A failed replacement remains actionable after device recovery until a
+    // same-GUID/sourceKey candidate is admitted and submitted successfully.
+    ...(recentFailure === undefined ? {} : { recentFailure }),
+    reset: Object.freeze([...state.reset, reason]),
+    receipt: Object.freeze({ ...state.receipt, committed: false }),
+  });
+}

package/src/pipeline/standard-output/resources.ts

@@ -0,0 +1,121 @@
+import type { World } from '@forgeax/engine-ecs';
+import { err, ok, type Result, RhiError } from '@forgeax/engine-rhi';
+import { toShared } from '@forgeax/engine-types';
+import type { RenderFrameState } from '../../record/frame-snapshot';
+import type { RenderSystemInternals } from '../../record/render-context';
+import type { CameraSnapshot } from '../../render-contract';
+import {
+  createAutoExposureGpuResources,
+  retireAutoExposureGpuResources,
+} from './auto-exposure/gpu';
+import { resetAutoExposureState } from './auto-exposure/state';
+import { prepareStandardLutGpu } from './lut-gpu';
+import { recordStandardLutFailure, resetStandardLutState } from './lut-state';
+
+/** Ordinary frames and detached recovery graphs prepare the same output resources. */
+export function prepareStandardOutputResources(
+  state: RenderFrameState,
+  internals: RenderSystemInternals,
+  camera: CameraSnapshot | undefined,
+  world: World,
+): Result<void, RhiError> {
+  const output = camera?.output;
+  if (output?.exposure.kind === 'auto') {
+    const pending = state.pendingAutoExposureGpuResources;
+    if (pending !== undefined && pending.device !== internals.device) {
+      retireAutoExposureGpuResources(pending);
+      state.pendingAutoExposureGpuResources = undefined;
+    }
+    if (
+      state.autoExposureGpuResources?.device !== internals.device &&
+      state.pendingAutoExposureGpuResources?.device !== internals.device
+    ) {
+      const resources = createAutoExposureGpuResources(
+        internals.device,
+        state.compiledFrameGraphGeneration,
+      );
+      if (!resources.ok) {
+        return err(
+          new RhiError({
+            code: 'webgpu-runtime-error',
+            expected: 'auto-exposure GPU resources are prepared before graph build',
+            hint: 'inspect the device capability and retry the current camera generation',
+            detail: {
+              error: { code: 'auto-exposure-prepare-failed', message: String(resources.error) },
+            },
+          }),
+        );
+      }
+      state.pendingAutoExposureGpuResources = resources.value;
+    }
+  } else {
+    if (state.pendingAutoExposureGpuResources !== undefined)
+      retireAutoExposureGpuResources(state.pendingAutoExposureGpuResources);
+    if (state.autoExposureGpuResources !== undefined)
+      retireAutoExposureGpuResources(state.autoExposureGpuResources);
+    state.pendingAutoExposureGpuResources = undefined;
+    state.autoExposureGpuResources = undefined;
+  }
+  if (output !== undefined && output.colorLutStrength > 0) {
+    const lut = prepareStandardLutGpu({
+      world,
+      handle: toShared<'TextureAsset'>(output.colorLut),
+      strength: output.colorLutStrength,
+      assets: internals.assets,
+      gpuStore: internals.gpuStore,
+      device: internals.device,
+    });
+    if (!lut.ok) {
+      state.standardLutState = recordStandardLutFailure(state.standardLutState, lut.error);
+      state.pendingStandardLutGpuResources = undefined;
+      return err(
+        new RhiError({
+          code: 'webgpu-runtime-error',
+          expected: 'the authored LUT resolves, is resident, and binds on the live device',
+          hint: 'inspect the LUT asset GUID and live capability before retrying',
+          detail: {
+            error: {
+              code: lut.error.code,
+              message: `${lut.error.expected}; ${lut.error.hint}; ${JSON.stringify(lut.error.detail)}`,
+            },
+          },
+        }),
+      );
+    }
+    const accepted = state.standardLutGpuResources;
+    if (
+      accepted?.sourceKey !== lut.value.sourceKey ||
+      accepted.texture !== lut.value.texture ||
+      accepted.strength !== lut.value.strength
+    ) {
+      state.pendingStandardLutGpuResources = lut.value;
+    }
+  } else {
+    state.pendingStandardLutGpuResources = undefined;
+    state.standardLutGpuResources = undefined;
+  }
+  return ok(undefined);
+}
+
+/** Drop lost-device handles without destroying them; retain only reset CPU/LKG facts. */
+export function resetStandardOutputForDeviceLoss(
+  state: RenderFrameState,
+  deviceEpoch: number,
+): void {
+  if (state.autoExposureState !== undefined) {
+    state.autoExposureState = resetAutoExposureState(state.autoExposureState, 'device-lost', {
+      targetGeneration: state.autoExposureState.targetGeneration + 1,
+      deviceEpoch,
+    });
+  }
+  state.standardLutState = resetStandardLutState(state.standardLutState, 'device-recovered', {
+    targetGeneration: state.standardLutState.targetGeneration + 1,
+    deviceEpoch,
+  });
+  state.pendingAutoExposureState = undefined;
+  state.pendingStandardLutState = undefined;
+  state.pendingAutoExposureGpuResources = undefined;
+  state.autoExposureGpuResources = undefined;
+  state.pendingStandardLutGpuResources = undefined;
+  state.standardLutGpuResources = undefined;
+}

package/src/pipeline/standard-output/types.ts

@@ -0,0 +1,58 @@
+import type { ColorValueDomain } from '@forgeax/engine-render-graph';
+
+export const STANDARD_OUTPUT_LOGICAL_STAGES = [
+  'temporal',
+  'meter',
+  'bloom',
+  'exposure-white-balance',
+  'tone',
+  'lut',
+  'fxaa',
+  'output-encoding',
+] as const;
+
+export type StandardOutputLogicalStage = (typeof STANDARD_OUTPUT_LOGICAL_STAGES)[number];
+export type StandardOutputLane = 'direct' | 'clustered';
+export type StandardOutputEncoding = 'explicit-oetf' | 'srgb-attachment';
+
+export interface StandardColorLutBinding {
+  readonly viewDimension: '3d';
+  readonly size: number;
+  readonly strength: number;
+}
+
+export interface StandardOutputRequest {
+  readonly lane: StandardOutputLane;
+  readonly temporal: boolean;
+  readonly meter: boolean;
+  readonly bloom: boolean;
+  readonly exposure: boolean;
+  readonly whiteBalance: boolean;
+  readonly lut: boolean;
+  readonly fxaa: boolean;
+  readonly outputEncoding: StandardOutputEncoding;
+}
+
+export interface StandardOutputPhysicalStage {
+  readonly name: StandardOutputLogicalStage;
+  readonly input: ColorValueDomain;
+  readonly output: ColorValueDomain;
+}
+
+export interface StandardOutputPlan {
+  readonly lane: StandardOutputLane;
+  readonly features: Readonly<
+    Pick<
+      StandardOutputRequest,
+      'temporal' | 'meter' | 'bloom' | 'exposure' | 'whiteBalance' | 'lut' | 'fxaa'
+    >
+  >;
+  readonly outputEncoding: StandardOutputEncoding;
+  readonly logicalStages: readonly StandardOutputLogicalStage[];
+  readonly physicalStages: readonly StandardOutputPhysicalStage[];
+  readonly finalWriterCount: 1;
+  readonly outputEncodingCount: 1;
+  readonly incrementalResources: readonly string[];
+  readonly incrementalBindings: number;
+  readonly incrementalTimestamps: number;
+}