@forgeax/engine-render 0.1.19 → 0.1.21

package/src/record/gpu-pass-timing/contract.ts

@@ -0,0 +1,180 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { GpuPassTimingJson, GpuPassTimingReason } from './errors.js';
+
+export const GPU_PASS_TIMING_SCHEMA_VERSION = '1.0' as const;
+
+export interface GpuPassTimingOptions {
+  readonly maxPassesPerFrame?: number | undefined;
+  readonly maxFramesInFlight?: number | undefined;
+  readonly retentionFrames?: number | undefined;
+}
+
+export interface NormalizedGpuPassTimingOptions {
+  readonly maxPassesPerFrame: number;
+  readonly maxFramesInFlight: number;
+  readonly retentionFrames: number;
+}
+
+export const DEFAULT_GPU_PASS_TIMING_OPTIONS: NormalizedGpuPassTimingOptions = Object.freeze({
+  maxPassesPerFrame: 256,
+  maxFramesInFlight: 3,
+  retentionFrames: 8,
+});
+
+function optionError(field: string, value: number, min: number, max: number): GpuPassTimingReason {
+  return {
+    code: 'invalid-timing-options',
+    expected: `${field} is an integer in [${min}, ${max}]`,
+    hint: `set ${field} to an integer in [${min}, ${max}]`,
+    detail: { field, value, min, max },
+  };
+}
+
+function validInteger(value: number, min: number, max: number): boolean {
+  return Number.isInteger(value) && value >= min && value <= max;
+}
+
+export function normalizeGpuPassTimingOptions(
+  options: GpuPassTimingOptions = {},
+): Result<NormalizedGpuPassTimingOptions, GpuPassTimingReason> {
+  const maxPassesPerFrame =
+    options.maxPassesPerFrame ?? DEFAULT_GPU_PASS_TIMING_OPTIONS.maxPassesPerFrame;
+  if (!validInteger(maxPassesPerFrame, 1, 2048)) {
+    return err(optionError('maxPassesPerFrame', maxPassesPerFrame, 1, 2048));
+  }
+  const maxFramesInFlight =
+    options.maxFramesInFlight ?? DEFAULT_GPU_PASS_TIMING_OPTIONS.maxFramesInFlight;
+  if (!validInteger(maxFramesInFlight, 1, 8)) {
+    return err(optionError('maxFramesInFlight', maxFramesInFlight, 1, 8));
+  }
+  const retentionFrames =
+    options.retentionFrames ?? DEFAULT_GPU_PASS_TIMING_OPTIONS.retentionFrames;
+  if (!validInteger(retentionFrames, 1, 8)) {
+    return err(optionError('retentionFrames', retentionFrames, 1, 8));
+  }
+  return ok(Object.freeze({ maxPassesPerFrame, maxFramesInFlight, retentionFrames }));
+}
+
+export interface GpuPassTimingPassIdentity {
+  readonly passName: string;
+  readonly passKind: 'raster' | 'compute' | 'copy';
+  readonly executionIndex: number;
+}
+
+export type GpuPassTimingMeasurementSource = 'pass-boundary' | 'copy-boundary-envelope';
+
+export interface GpuPassTimingMeasuredEntry extends GpuPassTimingPassIdentity {
+  readonly status: 'measured';
+  readonly measurementSource: GpuPassTimingMeasurementSource;
+  readonly beginningTick: string;
+  readonly endTick: string;
+  readonly durationNanoseconds: number;
+  readonly timerResolution?: 'equal-ticks' | undefined;
+}
+
+export interface GpuPassTimingUnmeasuredEntry extends GpuPassTimingPassIdentity {
+  readonly status: 'unmeasured';
+  readonly reason: GpuPassTimingReason;
+}
+
+export type GpuPassTimingEntry = GpuPassTimingMeasuredEntry | GpuPassTimingUnmeasuredEntry;
+
+export interface GpuPassTimingFrame {
+  readonly schemaVersion: typeof GPU_PASS_TIMING_SCHEMA_VERSION;
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+  readonly backendKind: RhiCaps['backendKind'];
+  readonly timestampPeriodNanoseconds: number;
+  readonly passCapacity: number;
+  readonly executedPassCount: number;
+  readonly measuredPassCount: number;
+  readonly droppedPassCount: number;
+  readonly passes: readonly GpuPassTimingEntry[];
+  readonly measuredPassNanoseconds: number;
+}
+
+export interface GpuPassTimingFrameInput {
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+  readonly backendKind: RhiCaps['backendKind'];
+  readonly timestampPeriodNanoseconds: number;
+  readonly passCapacity: number;
+  readonly passes: readonly GpuPassTimingEntry[];
+  readonly droppedPassCount?: number | undefined;
+}
+
+export interface GpuPassTimingRef {
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+}
+
+export interface GpuPassTimingCapability {
+  readonly timestampQuery: boolean;
+  readonly timestampPeriodNanoseconds: number | null;
+}
+
+/**
+ * Receipt-bound GPU pass facts. The four statuses are exhaustive: a caller can
+ * branch on `status` without guessing whether a missing duration means that
+ * the device lacks capability, the bounded capture failed, or a pass was
+ * intentionally left unmeasured. A pass duration is not frame latency.
+ */
+export type GpuPassTimingObservation =
+  | { readonly status: 'complete'; readonly frame: GpuPassTimingFrame }
+  | {
+      readonly status: 'partial';
+      readonly frame: GpuPassTimingFrame;
+      readonly reason: GpuPassTimingReason;
+    }
+  | {
+      readonly status: 'unavailable';
+      readonly reason: GpuPassTimingReason;
+      readonly capability: GpuPassTimingCapability;
+    }
+  | {
+      readonly status: 'failed';
+      readonly error: GpuPassTimingReason;
+      readonly latestKnownGood?: GpuPassTimingRef | undefined;
+    };
+
+function deepFreeze<T>(value: T): T {
+  if (value === null || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value as Record<string, unknown>)) deepFreeze(child);
+  return value;
+}
+
+export function createGpuPassTimingFrame(input: GpuPassTimingFrameInput): GpuPassTimingFrame {
+  let measuredPassCount = 0;
+  let measuredPassNanoseconds = 0;
+  for (const pass of input.passes) {
+    if (pass.status === 'measured') {
+      measuredPassCount += 1;
+      measuredPassNanoseconds += pass.durationNanoseconds;
+    }
+  }
+  return {
+    schemaVersion: GPU_PASS_TIMING_SCHEMA_VERSION,
+    frameId: input.frameId,
+    deviceGeneration: input.deviceGeneration,
+    graphGeneration: input.graphGeneration,
+    backendKind: input.backendKind,
+    timestampPeriodNanoseconds: input.timestampPeriodNanoseconds,
+    passCapacity: input.passCapacity,
+    executedPassCount: input.passes.length + (input.droppedPassCount ?? 0),
+    measuredPassCount,
+    droppedPassCount: input.droppedPassCount ?? 0,
+    passes: input.passes,
+    measuredPassNanoseconds,
+  };
+}
+
+export function freezeGpuPassTimingFrame(frame: GpuPassTimingFrame): GpuPassTimingFrame {
+  return deepFreeze(frame);
+}
+
+export type GpuPassTimingJsonObject = { readonly [key: string]: GpuPassTimingJson };

package/src/record/gpu-pass-timing/errors.ts

@@ -0,0 +1,34 @@
+export type GpuPassTimingReasonCode =
+  | 'gpu-timing-not-enabled'
+  | 'timestamp-query-unsupported'
+  | 'timestamp-period-unavailable'
+  | 'query-budget-exceeded'
+  | 'timing-in-flight-exhausted'
+  | 'timing-retention-expired'
+  | 'timestamp-write-unavailable'
+  | 'timestamp-owner-conflict'
+  | 'timestamp-resolve-failed'
+  | 'timestamp-readback-failed'
+  | 'timestamp-range-invalid'
+  | 'timing-device-generation-stale'
+  | 'timing-session-disposed'
+  | 'invalid-timing-options';
+
+export type GpuPassTimingJson =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly GpuPassTimingJson[]
+  | { readonly [key: string]: GpuPassTimingJson };
+
+export interface GpuPassTimingReason {
+  readonly code: GpuPassTimingReasonCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: { readonly [key: string]: GpuPassTimingJson };
+  readonly cause?: { readonly [key: string]: GpuPassTimingJson } | undefined;
+}
+
+export type GpuPassTimingError = GpuPassTimingReason;
+export type GpuPassTimingErrorCode = GpuPassTimingReasonCode;

package/src/record/gpu-pass-timing/index.ts

@@ -0,0 +1,37 @@
+export type {
+  GpuPassTimingCapability,
+  GpuPassTimingEntry,
+  GpuPassTimingFrame,
+  GpuPassTimingFrameInput,
+  GpuPassTimingMeasuredEntry,
+  GpuPassTimingMeasurementSource,
+  GpuPassTimingObservation,
+  GpuPassTimingOptions,
+  GpuPassTimingPassIdentity,
+  GpuPassTimingRef,
+  GpuPassTimingUnmeasuredEntry,
+  NormalizedGpuPassTimingOptions,
+} from './contract.js';
+export {
+  createGpuPassTimingFrame,
+  DEFAULT_GPU_PASS_TIMING_OPTIONS,
+  freezeGpuPassTimingFrame,
+  GPU_PASS_TIMING_SCHEMA_VERSION,
+  normalizeGpuPassTimingOptions,
+} from './contract.js';
+export type {
+  GpuPassTimingError,
+  GpuPassTimingErrorCode,
+  GpuPassTimingJson,
+  GpuPassTimingReason,
+  GpuPassTimingReasonCode,
+} from './errors.js';
+export type { GpuPassTimingTickInput, GpuPassTimingTickResult } from './parser.js';
+export { parseGpuPassTimingTicks } from './parser.js';
+export type {
+  GpuPassTimingCapture,
+  GpuPassTimingFrameIdentity,
+  GpuPassTimingSession,
+  GpuPassTimingSessionOptions,
+} from './session.js';
+export { createGpuPassTimingSession } from './session.js';

package/src/record/gpu-pass-timing/parser.ts

@@ -0,0 +1,97 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { GpuPassTimingMeasuredEntry } from './contract.js';
+import type { GpuPassTimingReason } from './errors.js';
+
+export interface GpuPassTimingTickInput {
+  readonly beginningTick: string;
+  readonly endTick: string;
+  readonly timestampPeriodNanoseconds: number;
+}
+
+export type GpuPassTimingTickResult = Omit<
+  GpuPassTimingMeasuredEntry,
+  'passName' | 'passKind' | 'executionIndex' | 'measurementSource'
+>;
+
+function failure(
+  code: GpuPassTimingReason['code'],
+  expected: string,
+  hint: string,
+  detail: { readonly [key: string]: null | boolean | number | string },
+): GpuPassTimingReason {
+  return { code, expected, hint, detail };
+}
+
+function decimal(value: string): bigint | undefined {
+  return /^(0|[1-9][0-9]*)$/.test(value) ? BigInt(value) : undefined;
+}
+
+export function parseGpuPassTimingTicks(
+  input: GpuPassTimingTickInput,
+): Result<GpuPassTimingTickResult, GpuPassTimingReason> {
+  const period = input.timestampPeriodNanoseconds;
+  if (!Number.isFinite(period) || period <= 0) {
+    return err(
+      failure(
+        'timestamp-period-unavailable',
+        'timestampPeriodNanoseconds is finite and greater than zero',
+        'use a device with a trustworthy positive timestamp period',
+        { timestampPeriodNanoseconds: period },
+      ),
+    );
+  }
+  const beginning = decimal(input.beginningTick);
+  const end = decimal(input.endTick);
+  if (beginning === undefined || end === undefined) {
+    return err(
+      failure(
+        'timestamp-range-invalid',
+        'raw timestamp ticks are unsigned decimal strings',
+        'retain the GPU u64 readback as a decimal string before parsing',
+        { beginningTick: input.beginningTick, endTick: input.endTick },
+      ),
+    );
+  }
+  if (end < beginning) {
+    return err(
+      failure(
+        'timestamp-range-invalid',
+        'end tick is greater than or equal to beginning tick',
+        'discard the readback and wait for a later receipt',
+        { beginningTick: input.beginningTick, endTick: input.endTick },
+      ),
+    );
+  }
+  const delta = end - beginning;
+  if (delta > BigInt(Number.MAX_SAFE_INTEGER)) {
+    return err(
+      failure(
+        'timestamp-range-invalid',
+        'tick delta converts to a safe finite duration',
+        'use a bounded timestamp range or capture a later receipt',
+        { beginningTick: input.beginningTick, endTick: input.endTick },
+      ),
+    );
+  }
+  const durationNanoseconds = Number(delta) * period;
+  if (
+    !Number.isFinite(durationNanoseconds) ||
+    !Number.isSafeInteger(Math.round(durationNanoseconds))
+  ) {
+    return err(
+      failure(
+        'timestamp-range-invalid',
+        'derived duration is finite and safely representable',
+        'use a smaller tick range or a trustworthy timestamp period',
+        { timestampPeriodNanoseconds: period },
+      ),
+    );
+  }
+  return ok({
+    status: 'measured',
+    beginningTick: input.beginningTick,
+    endTick: input.endTick,
+    durationNanoseconds,
+    ...(delta === 0n ? { timerResolution: 'equal-ticks' as const } : {}),
+  });
+}