@forgeax/engine-render 0.1.27 → 0.1.29

package/src/pipeline/standard-output/auto-exposure/graph.ts

@@ -0,0 +1,221 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { RenderPipelineFrame } from '../../../render-pipeline';
+import { AUTO_EXPOSURE_PRESET_V1 } from './preset';
+
+export const AUTO_EXPOSURE_GRAPH_PASSES = [
+  'auto-exposure-clear',
+  'auto-exposure-histogram',
+  'auto-exposure-adapt',
+] as const;
+
+/** The logical meter stages are encoded inside one physical compute pass. */
+export const AUTO_EXPOSURE_FUSED_GRAPH_PASS = 'auto-exposure-meter' as const;
+
+/**
+ * The meter keeps one physical compute pass, but separates its ordered
+ * clear/histogram/adapt dispatches so the histogram cohort can synchronize
+ * across workgroups through the command stream. Histogram uses 32 fixed
+ * workgroups of 256 invocations; the dispatch is intentionally independent of
+ * output resolution.
+ */
+export const AUTO_EXPOSURE_HISTOGRAM_WORKGROUP_SIZE = 256 as const;
+export const AUTO_EXPOSURE_HISTOGRAM_WORKGROUP_COUNT = 32 as const;
+export const AUTO_EXPOSURE_HISTOGRAM_DISPATCH = Object.freeze({
+  x: 4,
+  y: 8,
+  z: 1,
+} as const);
+export const AUTO_EXPOSURE_ADAPT_WORKGROUP_SIZE = 64 as const;
+export const AUTO_EXPOSURE_CLEAR_WORKGROUP_SIZE = 256 as const;
+
+export type AutoExposureGraphPassName = (typeof AUTO_EXPOSURE_GRAPH_PASSES)[number];
+
+/**
+ * Built-in auto-exposure work is recorded synchronously during graph
+ * execution. Prefer the renderer's handle-first factory so the first frame
+ * does not become a false pending shader failure after async warm-up has
+ * already supplied a usable module.
+ */
+export function resolveAutoExposureShaderModuleFactory(
+  runtime: Pick<
+    RenderPipelineFrame['runtime'],
+    'immediateShaderModuleFactory' | 'shaderModuleFactory'
+  >,
+): NonNullable<RenderPipelineFrame['runtime']['shaderModuleFactory']> | undefined {
+  return runtime.immediateShaderModuleFactory ?? runtime.shaderModuleFactory;
+}
+
+export interface AutoExposureGraphPass {
+  readonly name: AutoExposureGraphPassName;
+  readonly kind: 'compute';
+  readonly workgroupSize: readonly [number, number, number];
+}
+
+export interface AutoExposureGraphPlan {
+  readonly resolution: Readonly<{ width: number; height: number }>;
+  readonly sampleBounds: Readonly<{ x: 4; y: 4 }>;
+  readonly sampleCount: number;
+  readonly dispatch: Readonly<{ x: number; y: number; z: 1 }>;
+  readonly histogramBytes: 1024;
+  readonly stateBytes: 32;
+  readonly passes: readonly AutoExposureGraphPass[];
+  readonly physicalPass: typeof AUTO_EXPOSURE_FUSED_GRAPH_PASS;
+  readonly physicalPassCount: 1;
+  readonly resources: readonly ['auto-exposure-histogram', 'auto-exposure-state'];
+  readonly cpuReadbackCount: 0;
+  readonly cpuUploadCount: 0;
+  readonly candidateAvailableSameFrame: true;
+}
+
+export class AutoExposureGraphError extends Error {
+  readonly code = 'auto-exposure-graph-invalid' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: Readonly<{ field: string; actual: string }>;
+
+  constructor(field: string, actual: string, expected: string) {
+    super(`auto-exposure-graph-invalid: ${field} ${actual}; expected ${expected}`);
+    this.name = 'AutoExposureGraphError';
+    this.expected = expected;
+    this.hint = `repair the ${field} declaration before recording the auto exposure graph`;
+    this.detail = Object.freeze({ field, actual });
+  }
+}
+
+function positiveDimension(value: number): boolean {
+  return Number.isInteger(value) && value > 0;
+}
+
+export function createAutoExposureGraphPlan(input: {
+  readonly width: number;
+  readonly height: number;
+}): AutoExposureGraphPlan {
+  if (!positiveDimension(input.width) || !positiveDimension(input.height)) {
+    throw new RangeError(
+      'Auto exposure graph resolution must contain positive integer dimensions.',
+    );
+  }
+  const block = AUTO_EXPOSURE_PRESET_V1.sampleBlockSize;
+  const histogramDispatch = AUTO_EXPOSURE_HISTOGRAM_DISPATCH;
+  return {
+    resolution: Object.freeze({ width: input.width, height: input.height }),
+    sampleBounds: Object.freeze({ x: block, y: block }),
+    sampleCount: 1,
+    dispatch: histogramDispatch,
+    histogramBytes: (256 * 4) as 1024,
+    stateBytes: (2 * 16) as 32,
+    physicalPass: AUTO_EXPOSURE_FUSED_GRAPH_PASS,
+    physicalPassCount: 1,
+    passes: Object.freeze([
+      {
+        name: 'auto-exposure-clear',
+        kind: 'compute',
+        workgroupSize: [AUTO_EXPOSURE_CLEAR_WORKGROUP_SIZE, 1, 1],
+      },
+      {
+        name: 'auto-exposure-histogram',
+        kind: 'compute',
+        workgroupSize: [AUTO_EXPOSURE_HISTOGRAM_WORKGROUP_SIZE, 1, 1],
+      },
+      {
+        name: 'auto-exposure-adapt',
+        kind: 'compute',
+        workgroupSize: [AUTO_EXPOSURE_ADAPT_WORKGROUP_SIZE, 1, 1],
+      },
+    ]),
+    resources: Object.freeze(['auto-exposure-histogram', 'auto-exposure-state']),
+    cpuReadbackCount: 0,
+    cpuUploadCount: 0,
+    candidateAvailableSameFrame: true,
+  };
+}
+
+export function validateAutoExposureGraphPlan(
+  plan: AutoExposureGraphPlan,
+): Result<AutoExposureGraphPlan, AutoExposureGraphError> {
+  const expectedPasses = [...AUTO_EXPOSURE_GRAPH_PASSES];
+  if (
+    plan.passes.length !== expectedPasses.length ||
+    plan.passes.some(
+      (pass, index) => pass.name !== expectedPasses[index] || pass.kind !== 'compute',
+    )
+  ) {
+    return err(
+      new AutoExposureGraphError(
+        'passes',
+        plan.passes.map((pass) => pass.name).join(','),
+        expectedPasses.join(','),
+      ),
+    );
+  }
+  const expectedDispatch = AUTO_EXPOSURE_HISTOGRAM_DISPATCH;
+  if (
+    plan.dispatch.x !== expectedDispatch.x ||
+    plan.dispatch.y !== expectedDispatch.y ||
+    plan.dispatch.z !== expectedDispatch.z ||
+    plan.dispatch.x * plan.dispatch.y * plan.dispatch.z !== AUTO_EXPOSURE_HISTOGRAM_WORKGROUP_COUNT
+  ) {
+    return err(
+      new AutoExposureGraphError(
+        'dispatch',
+        `${plan.dispatch.x}x${plan.dispatch.y}x${plan.dispatch.z}`,
+        `${expectedDispatch.x}x${expectedDispatch.y}x${expectedDispatch.z}`,
+      ),
+    );
+  }
+  const expectedWorkgroupSizes = [
+    [AUTO_EXPOSURE_CLEAR_WORKGROUP_SIZE, 1, 1],
+    [AUTO_EXPOSURE_HISTOGRAM_WORKGROUP_SIZE, 1, 1],
+    [AUTO_EXPOSURE_ADAPT_WORKGROUP_SIZE, 1, 1],
+  ] as const;
+  if (
+    plan.passes.some((pass, index) => {
+      const expected = expectedWorkgroupSizes[index];
+      return (
+        expected === undefined ||
+        pass.workgroupSize.some((value, dimension) => value !== expected[dimension])
+      );
+    })
+  ) {
+    return err(
+      new AutoExposureGraphError(
+        'workgroupSize',
+        plan.passes.map((pass) => pass.workgroupSize.join('x')).join(','),
+        expectedWorkgroupSizes.map((size) => size.join('x')).join(','),
+      ),
+    );
+  }
+  if (plan.histogramBytes !== 1024) {
+    return err(new AutoExposureGraphError('histogramBytes', String(plan.histogramBytes), '1024'));
+  }
+  if (plan.stateBytes !== 32) {
+    return err(new AutoExposureGraphError('stateBytes', String(plan.stateBytes), '32'));
+  }
+  if (plan.physicalPass !== AUTO_EXPOSURE_FUSED_GRAPH_PASS) {
+    return err(
+      new AutoExposureGraphError(
+        'physicalPass',
+        String(plan.physicalPass),
+        AUTO_EXPOSURE_FUSED_GRAPH_PASS,
+      ),
+    );
+  }
+  if (plan.physicalPassCount !== 1) {
+    return err(
+      new AutoExposureGraphError('physicalPassCount', String(plan.physicalPassCount), '1'),
+    );
+  }
+  if (plan.cpuReadbackCount !== 0 || plan.cpuUploadCount !== 0) {
+    return err(
+      new AutoExposureGraphError(
+        'cpuTransfers',
+        `${plan.cpuReadbackCount}/${plan.cpuUploadCount}`,
+        '0/0',
+      ),
+    );
+  }
+  if (!plan.candidateAvailableSameFrame) {
+    return err(new AutoExposureGraphError('candidateAvailableSameFrame', 'false', 'true'));
+  }
+  return ok(plan);
+}

package/src/pipeline/standard-output/auto-exposure/inspection.ts

@@ -0,0 +1,231 @@
+import type { CameraExposure } from '../../../components/camera';
+
+export type AutoExposureErrorCode =
+  | 'auto-exposure-invalid-parameter'
+  | 'auto-exposure-capability-unavailable'
+  | 'auto-exposure-stale-generation'
+  | 'auto-exposure-stage-failed';
+
+export interface AutoExposureInvalidParameterDetail {
+  readonly field: string;
+  readonly value: number;
+  readonly expected: string;
+}
+
+export interface AutoExposureCapabilityUnavailableDetail {
+  readonly capability: 'compute' | 'storage-buffer' | 'float-filterable';
+  readonly generation: number;
+}
+
+export interface AutoExposureStaleGenerationDetail {
+  readonly expectedGeneration: number;
+  readonly actualGeneration: number;
+}
+
+export interface AutoExposureStageFailedDetail {
+  readonly stage: 'prepare' | 'record';
+  readonly operation: string;
+  readonly cause: unknown;
+}
+
+export type AutoExposureErrorDetailByCode = {
+  'auto-exposure-invalid-parameter': AutoExposureInvalidParameterDetail;
+  'auto-exposure-capability-unavailable': AutoExposureCapabilityUnavailableDetail;
+  'auto-exposure-stale-generation': AutoExposureStaleGenerationDetail;
+  'auto-exposure-stage-failed': AutoExposureStageFailedDetail;
+};
+
+export type AutoExposureErrorDetail = AutoExposureErrorDetailByCode[AutoExposureErrorCode];
+
+export class AutoExposureInvalidParameterError extends Error {
+  readonly code = 'auto-exposure-invalid-parameter' as const;
+  readonly expected = ERROR_POLICY[this.code].expected;
+  readonly hint = ERROR_POLICY[this.code].hint;
+  constructor(readonly detail: AutoExposureInvalidParameterDetail) {
+    super(`auto-exposure-invalid-parameter: ${detail.field}`);
+    this.name = 'AutoExposureInvalidParameterError';
+  }
+}
+
+export class AutoExposureCapabilityUnavailableError extends Error {
+  readonly code = 'auto-exposure-capability-unavailable' as const;
+  readonly expected = ERROR_POLICY[this.code].expected;
+  readonly hint = ERROR_POLICY[this.code].hint;
+  constructor(readonly detail: AutoExposureCapabilityUnavailableDetail) {
+    super(`auto-exposure-capability-unavailable: ${detail.capability}`);
+    this.name = 'AutoExposureCapabilityUnavailableError';
+  }
+}
+
+export class AutoExposureStaleGenerationError extends Error {
+  readonly code = 'auto-exposure-stale-generation' as const;
+  readonly expected = ERROR_POLICY[this.code].expected;
+  readonly hint = ERROR_POLICY[this.code].hint;
+  constructor(readonly detail: AutoExposureStaleGenerationDetail) {
+    super(
+      `auto-exposure-stale-generation: ${detail.actualGeneration} != ${detail.expectedGeneration}`,
+    );
+    this.name = 'AutoExposureStaleGenerationError';
+  }
+}
+
+export class AutoExposureStageFailedError extends Error {
+  readonly code = 'auto-exposure-stage-failed' as const;
+  readonly expected = ERROR_POLICY[this.code].expected;
+  readonly hint = ERROR_POLICY[this.code].hint;
+  constructor(readonly detail: AutoExposureStageFailedDetail) {
+    super(`auto-exposure-stage-failed: ${detail.operation}`);
+    this.name = 'AutoExposureStageFailedError';
+  }
+}
+
+export type AutoExposureError =
+  | AutoExposureInvalidParameterError
+  | AutoExposureCapabilityUnavailableError
+  | AutoExposureStaleGenerationError
+  | AutoExposureStageFailedError;
+
+type AutoExposureErrorInput = {
+  [C in AutoExposureErrorCode]: {
+    readonly code: C;
+    readonly detail: AutoExposureErrorDetailByCode[C];
+  };
+}[AutoExposureErrorCode];
+
+export type AutoExposureErrorRecord = {
+  [C in AutoExposureErrorCode]: {
+    readonly code: C;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: AutoExposureErrorDetailByCode[C];
+  };
+}[AutoExposureErrorCode];
+
+export type AutoExposureResetReason =
+  | 'camera-change'
+  | 'manual-mode'
+  | 'device-lost'
+  | 'stale-generation';
+
+export interface AutoExposureCost {
+  readonly histogramBytes: number;
+  /** Logical stages retained for the inspect contract: clear, histogram, adapt. */
+  readonly passCount: number;
+  /** The logical stages share one real timestamped compute pass. */
+  readonly physicalPassCount: number;
+}
+
+export interface AutoExposureReceipt {
+  readonly frameId: number;
+  readonly committed: boolean;
+}
+
+/**
+ * Describes where the detached `actual` value came from.  A successful live
+ * GPU submission is intentionally not a CPU observation: its numeric result
+ * remains resident in the GPU state buffer until an explicit readback owner
+ * is requested.  Keeping that state distinct prevents fallback from being
+ * presented as the measured exposure.
+ */
+export type AutoExposureActualState = 'accepted' | 'fallback' | 'gpu-resident';
+
+export interface AutoExposureInspection {
+  readonly requested: CameraExposure;
+  readonly actual: number | null;
+  readonly actualState: AutoExposureActualState;
+  readonly fallback: number;
+  readonly lastKnownGood: number;
+  readonly targetGeneration: number;
+  readonly recentFailure?: AutoExposureError;
+  readonly reset: readonly AutoExposureResetReason[];
+  readonly cost: AutoExposureCost;
+  readonly receipt: AutoExposureReceipt;
+}
+
+export interface AutoExposureInspectionInput
+  extends Omit<AutoExposureInspection, 'actualState' | 'recentFailure'> {
+  readonly actualState?: AutoExposureActualState;
+  readonly recentFailure?: AutoExposureError | AutoExposureErrorRecord;
+}
+
+const ERROR_POLICY: Readonly<
+  Record<AutoExposureErrorCode, { readonly expected: string; readonly hint: string }>
+> = {
+  'auto-exposure-invalid-parameter': {
+    expected: 'camera auto-exposure parameters are finite and within their declared ranges',
+    hint: 'inspect the field and provide a finite value before rebuilding the camera output',
+  },
+  'auto-exposure-capability-unavailable': {
+    expected: 'the auto-exposure stage has the required device capability',
+    hint: 'inspect live capabilities and retry the same camera generation',
+  },
+  'auto-exposure-stale-generation': {
+    expected: 'the prepared auto-exposure state matches the camera target generation',
+    hint: 'discard stale prepared state and rebuild from the latest camera snapshot',
+  },
+  'auto-exposure-stage-failed': {
+    expected: 'the auto-exposure stage completes its declared operation',
+    hint: 'inspect the structured cause, preserve lastKnownGood, and retry the stage',
+  },
+};
+
+export function createAutoExposureError(
+  input: AutoExposureErrorInput | AutoExposureErrorRecord,
+): AutoExposureError {
+  if (
+    input instanceof AutoExposureInvalidParameterError ||
+    input instanceof AutoExposureCapabilityUnavailableError ||
+    input instanceof AutoExposureStaleGenerationError ||
+    input instanceof AutoExposureStageFailedError
+  ) {
+    return input;
+  }
+  switch (input.code) {
+    case 'auto-exposure-invalid-parameter':
+      return new AutoExposureInvalidParameterError(input.detail);
+    case 'auto-exposure-capability-unavailable':
+      return new AutoExposureCapabilityUnavailableError(input.detail);
+    case 'auto-exposure-stale-generation':
+      return new AutoExposureStaleGenerationError(input.detail);
+    case 'auto-exposure-stage-failed':
+      return new AutoExposureStageFailedError(input.detail);
+  }
+}
+
+function cloneExposure(exposure: CameraExposure): CameraExposure {
+  if (exposure.kind === 'manual') return { ...exposure };
+  return {
+    ...exposure,
+    rangeEv: [exposure.rangeEv[0], exposure.rangeEv[1]],
+    rates: [exposure.rates[0], exposure.rates[1]],
+  };
+}
+
+function cloneFailure(error: AutoExposureError | undefined): AutoExposureError | undefined {
+  if (error === undefined) return undefined;
+  return Object.freeze({
+    ...error,
+    detail: Object.freeze({ ...error.detail }),
+  }) as AutoExposureError;
+}
+
+/** Project detached bounded facts; GPU handles and histogram buckets never cross this boundary. */
+export function createAutoExposureInspection(
+  input: AutoExposureInspectionInput,
+): Readonly<AutoExposureInspection> {
+  const base = {
+    requested: cloneExposure(input.requested),
+    actual: input.actual,
+    actualState: input.actualState ?? (input.actual === null ? 'gpu-resident' : 'accepted'),
+    fallback: input.fallback,
+    lastKnownGood: input.lastKnownGood,
+    targetGeneration: input.targetGeneration,
+    reset: Object.freeze([...input.reset]),
+    cost: Object.freeze({ ...input.cost }),
+    receipt: Object.freeze({ ...input.receipt }),
+  };
+  if (input.recentFailure === undefined) return Object.freeze(base);
+  const recentFailure = cloneFailure(createAutoExposureError(input.recentFailure));
+  if (recentFailure === undefined) return Object.freeze(base);
+  return Object.freeze({ ...base, recentFailure });
+}