@forgeax/engine-rhi-debug 0.0.0-dev.8d955ade1c79

package/src/recorder/snapshot.ts

@@ -0,0 +1,38 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { createRhiDebugError, type RhiDebugError } from '../errors';
+import type { DebugRhiInstance } from '../recorder';
+import type { ResourceRegistry } from './resource-registry';
+
+export interface SnapshotOptions {
+  readonly snapshotTimeoutMs: number;
+  readonly byteBudget: number;
+}
+
+export async function snapshotFrame(
+  recorder: DebugRhiInstance,
+  registry: ResourceRegistry,
+  options: SnapshotOptions,
+): Promise<Result<void, RhiDebugError>> {
+  const estimatedBytes = registry.estimateSnapshotBytes();
+  const requiredBytes = Math.max(1, estimatedBytes);
+  if (requiredBytes > options.byteBudget) {
+    return err(
+      createRhiDebugError('capture-snapshot-failed', {
+        stage: 'snapshot',
+        cause: `snapshot byte budget ${options.byteBudget} is smaller than the ${requiredBytes}-byte capture minimum`,
+      }),
+    );
+  }
+  try {
+    const result = await recorder.snapshotAllLiveResources(options.snapshotTimeoutMs);
+    if (result.ok) return ok(undefined);
+    return err(result.error);
+  } catch (cause) {
+    return err(
+      createRhiDebugError('capture-snapshot-failed', {
+        stage: 'snapshot',
+        cause: String(cause),
+      }),
+    );
+  }
+}

package/src/recorder/wrap.ts

@@ -0,0 +1,157 @@
+// @forgeax/engine-rhi-debug/src/recorder/wrap -- RHI instance assembly.
+
+/// <reference types="@webgpu/types" />
+
+import type {
+  RequestAdapterOptions,
+  RequestDeviceOptions,
+  Result,
+  RhiAdapter,
+  RhiDevice,
+  RhiInstance,
+  ShaderModule,
+} from '@forgeax/engine-rhi';
+import { ok as makeOk } from '@forgeax/engine-types';
+import type { HandleId, RhiCallEvent } from '../types';
+import {
+  type DebugRhiInstance,
+  pushEvent,
+  type RecorderInternal,
+  RecorderState,
+  registerHandle,
+} from './core';
+import { createDeviceProxy } from './device';
+import { createRecorderLifecycle } from './lifecycle';
+
+export function wrap(instance: RhiInstance): DebugRhiInstance {
+  const s: RecorderInternal = {
+    state: RecorderState.Idle,
+    requestedFrames: 0,
+    recordedFrames: 0,
+    events: [],
+    blobPool: new Map(),
+    handleMap: new WeakMap(),
+    textureViewHandleMap: new WeakMap(),
+    bootstrapCreates: new Map(),
+    snapshotSeededHandles: new Set(),
+    snapshotGeneration: 0,
+    snapshotProgress: undefined,
+    descriptorTable: new Map(),
+    _skipRecord: false,
+    frameIdx: 0,
+    bootstrap: true,
+    recordedCaps: undefined,
+    valid: true,
+    capturedDevice: undefined,
+  };
+
+  const lifecycle = createRecorderLifecycle(s);
+  const {
+    arm,
+    onFrameEnd,
+    getTape,
+    getState,
+    getEvents,
+    getBlobPool,
+    transitionToError,
+    disposeError,
+    snapshotResource,
+    snapshotAllLiveResources,
+  } = lifecycle;
+
+  const debugInst: DebugRhiInstance = {
+    arm,
+    onFrameEnd,
+    getTape,
+    getState,
+    getEvents,
+    getBlobPool,
+    transitionToError,
+    disposeError,
+    snapshotResource,
+    snapshotAllLiveResources,
+    pushExternalEvent(event: RhiCallEvent): void {
+      pushEvent(s, event);
+    },
+    registerShaderModule(handle: ShaderModule, handleId: HandleId): void {
+      s.handleMap.set(handle as object, handleId);
+    },
+    pushExternalCreateEvent(handle: object, kind: string, event: RhiCallEvent): HandleId {
+      const hId = registerHandle(s, handle, kind, event);
+      pushEvent(s, event);
+      return hId;
+    },
+    resetForDeviceLoss(): void {
+      // A lost GPU device invalidates every opaque handle and every descriptor
+      // entry. Keep the recorder usable for the renderer's subsequent rebuild:
+      // resource and shader creation calls during recovery repopulate these
+      // registries against the fresh device before the next capture arms.
+      s.state = RecorderState.Idle;
+      s.requestedFrames = 0;
+      s.recordedFrames = 0;
+      s.events = [];
+      s.blobPool = new Map();
+      s.handleMap = new WeakMap();
+      s.textureViewHandleMap = new WeakMap();
+      s.bootstrapCreates = new Map();
+      s.descriptorTable = new Map();
+      s.snapshotSeededHandles = new Set();
+      s.snapshotProgress = undefined;
+      s.frameIdx = 0;
+      s.bootstrap = true;
+      s.recordedCaps = undefined;
+      s.valid = true;
+      s.capturedDevice = undefined;
+    },
+    valid(): boolean {
+      return s.valid;
+    },
+    bootstrapCreatesSize(): number {
+      return s.bootstrapCreates.size;
+    },
+    bootstrapEvents(): readonly RhiCallEvent[] {
+      return Array.from(s.bootstrapCreates.values());
+    },
+    descriptorTable() {
+      return s.descriptorTable;
+    },
+
+    async requestAdapter(
+      opts?: RequestAdapterOptions | undefined,
+      compatibleSurface?: HTMLCanvasElement | OffscreenCanvas | undefined,
+    ) {
+      const res = await instance.requestAdapter(opts, compatibleSurface);
+      if (!res.ok) return res;
+
+      const realAdapter = res.value;
+      const proxyAdapter: RhiAdapter = {
+        features: realAdapter.features,
+        limits: realAdapter.limits,
+        async requestDevice(devOpts?: RequestDeviceOptions | undefined) {
+          const devRes = await realAdapter.requestDevice(devOpts);
+          if (!devRes.ok) return devRes;
+          // Keep the proxied device available for recorder-owned readback.
+          const proxied = createDeviceProxy(s, devRes.value);
+          s.capturedDevice = proxied;
+          s.recordedCaps = {
+            // RhiDevice does not own a canvas, so retain the existing tape
+            // default for this informational field while deriving every
+            // device-backed capability from the captured device.
+            canvasFormat: 'bgra8unorm' as GPUTextureFormat,
+            rgba16floatRenderable: proxied.caps.rgba16floatRenderable,
+            float32Filterable: proxied.caps.float32Filterable,
+            textureCompressionBc: proxied.caps.textureCompressionBc,
+            textureCompressionEtc2: proxied.caps.textureCompressionEtc2,
+            textureCompressionAstc: proxied.caps.textureCompressionAstc,
+            storageBuffer: proxied.caps.storageBuffer,
+            timestampQuery: proxied.caps.timestampQuery,
+          };
+          return makeOk(proxied) as Result<RhiDevice, import('@forgeax/engine-rhi').RhiError>;
+        },
+      };
+      return makeOk(proxyAdapter) as Result<RhiAdapter, import('@forgeax/engine-rhi').RhiError>;
+    },
+  };
+
+  return debugInst;
+}

package/src/recorder.ts

@@ -0,0 +1,15 @@
+// @forgeax/engine-rhi-debug/src/recorder -- split recorder public seam.
+
+export type { CreateShaderModuleFn, DebugRhiInstance } from './recorder/core';
+export { PER_EVENT_OVERHEAD, TAPE_FORMAT_VERSION } from './recorder/core';
+export type {
+  CaptureFrameOptions,
+  EncodedTape,
+  RecordableBackend,
+  RecorderAttachment,
+  RecorderBackend,
+  RecorderOptions,
+} from './recorder/session';
+export { attachRecorder } from './recorder/session';
+export { wrapCreateShaderModule } from './recorder/shader';
+export { wrap } from './recorder/wrap';

package/src/replay/device-request.ts

@@ -0,0 +1,38 @@
+import type { Tape } from '../protocol/types';
+
+const RECORDED_CAPABILITY_FEATURES = [
+  ['timestampQuery', 'timestamp-query'],
+  ['textureCompressionBc', 'texture-compression-bc'],
+  ['textureCompressionEtc2', 'texture-compression-etc2'],
+  ['textureCompressionAstc', 'texture-compression-astc'],
+  ['firstInstanceIndirect', 'indirect-first-instance'],
+  ['float32Filterable', 'float32-filterable'],
+  ['rg11b10ufloatRenderable', 'rg11b10ufloat-renderable'],
+] as const satisfies readonly (readonly [string, GPUFeatureName])[];
+
+/**
+ * Build the strongest fresh WebGPU device the current adapter can provide for
+ * a recorded tape. Optional features must be enabled, not merely advertised,
+ * and replay receives concrete adapter limits instead of lower device defaults.
+ */
+export function replayDeviceRequest(
+  tape: Tape,
+  adapterFeatures: ReadonlySet<GPUFeatureName>,
+  adapterLimits: Readonly<Record<string, number>>,
+): GPUDeviceDescriptor {
+  const requiredFeatures = RECORDED_CAPABILITY_FEATURES.filter(
+    ([capability, feature]) =>
+      tape.header.rhiCaps[capability] === true && adapterFeatures.has(feature),
+  ).map(([, feature]) => feature);
+  const limitEntries = Object.entries(adapterLimits).filter(
+    ([, value]) => Number.isFinite(value) && value >= 0,
+  );
+  const request: GPUDeviceDescriptor = {};
+  if (requiredFeatures.length > 0) request.requiredFeatures = requiredFeatures;
+  if (limitEntries.length > 0) {
+    request.requiredLimits = Object.fromEntries(limitEntries) as NonNullable<
+      GPUDeviceDescriptor['requiredLimits']
+    >;
+  }
+  return request;
+}

package/src/replay/execute-support.ts

@@ -0,0 +1,243 @@
+// @forgeax/engine-rhi-debug/src/replay/execute-support -- replay event helpers.
+
+import type {
+  Buffer,
+  RhiCommandEncoder,
+  RhiComputePassEncoder,
+  RhiRenderPassEncoder,
+} from '@forgeax/engine-rhi';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { createRhiDebugError, type RhiDebugError } from '../errors';
+import type { RhiCallEvent, Tape } from '../protocol/types';
+import type { ReplayExecutionContext } from './execute';
+import type { ReplayResource } from './resources';
+
+type ReplayPass = RhiRenderPassEncoder & RhiComputePassEncoder;
+
+export function eventRecord(event: RhiCallEvent): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(event));
+}
+
+export function eventFailure(
+  eventIndex: number,
+  event: RhiCallEvent,
+  stage: 'lookup' | 'create' | 'write' | 'encode' | 'finish' | 'submit',
+  cause: unknown,
+): Result<never, RhiDebugError> {
+  return err(
+    createRhiDebugError('replay-event-failed', {
+      eventIndex,
+      kind: event.kind,
+      stage,
+      cause: cause instanceof Error ? cause.message : String(cause),
+    }),
+  );
+}
+
+export function blob(
+  tape: Tape,
+  hash: string,
+  event: RhiCallEvent,
+  eventIndex: number,
+): Result<Uint8Array, RhiDebugError> {
+  const found = tape.blobs.find((candidate) => candidate.hash === hash);
+  return found === undefined
+    ? eventFailure(eventIndex, event, 'lookup', `blob ${hash} is missing`)
+    : ok(found.bytes);
+}
+
+export function clearBuffer(
+  context: ReplayExecutionContext,
+  event: Extract<RhiCallEvent, { kind: 'clearBuffer' }>,
+  eventIndex: number,
+): Result<void, RhiDebugError> {
+  const encoder = requireResource<RhiCommandEncoder>(
+    context,
+    event.cmdHandleId,
+    'encoder',
+    eventIndex,
+    event.kind,
+    'command',
+  );
+  const buffer = requireResource<Buffer>(context, event.handleId, 'buffer', eventIndex, event.kind);
+  if (!encoder.ok) return encoder;
+  if (!buffer.ok) return buffer;
+  encoder.value.clearBuffer(buffer.value, event.offset, event.size);
+  return ok(undefined);
+}
+
+export function commandEncoderCall(
+  context: ReplayExecutionContext,
+  event: Extract<RhiCallEvent, { kind: 'pushDebugGroup' | 'popDebugGroup' | 'insertDebugMarker' }>,
+  eventIndex: number,
+  call: (encoder: RhiCommandEncoder) => void,
+): Result<void, RhiDebugError> {
+  const encoder = requireResource<RhiCommandEncoder>(
+    context,
+    event.cmdHandleId,
+    'encoder',
+    eventIndex,
+    event.kind,
+    'command',
+  );
+  if (!encoder.ok) return encoder;
+  call(encoder.value);
+  return ok(undefined);
+}
+
+export function finish(
+  context: ReplayExecutionContext,
+  event: Extract<RhiCallEvent, { kind: 'finish' }>,
+  eventIndex: number,
+): Result<void, RhiDebugError> {
+  const encoder = requireResource<RhiCommandEncoder>(
+    context,
+    event.cmdHandleId,
+    'encoder',
+    eventIndex,
+    event.kind,
+    'command',
+  );
+  if (!encoder.ok) return encoder;
+  const result = encoder.value.finish();
+  if (!result.ok) return eventFailure(eventIndex, event, 'finish', result.error);
+  return context.table.set(
+    event.cmdHandleId,
+    { kind: 'encoder', role: 'command-buffer', value: result.value },
+    eventRecord(event),
+  );
+}
+
+export function endPass(
+  context: ReplayExecutionContext,
+  event: Extract<RhiCallEvent, { kind: 'endRenderPass' | 'endComputePass' }>,
+  eventIndex: number,
+  role: 'render-pass' | 'compute-pass',
+): Result<void, RhiDebugError> {
+  const pass = requireResource<RhiRenderPassEncoder | RhiComputePassEncoder>(
+    context,
+    event.passHandleId,
+    'encoder',
+    eventIndex,
+    event.kind,
+    role,
+  );
+  if (!pass.ok) return pass;
+  pass.value.end();
+  context.table.delete(event.passHandleId);
+  return ok(undefined);
+}
+
+export function seedInitialData(
+  context: ReplayExecutionContext,
+  event: Extract<RhiCallEvent, { kind: 'initialData' }>,
+  eventIndex: number,
+): Result<void, RhiDebugError> {
+  const entry = context.table.get(event.handleId);
+  const bytes = blob(context.tape, event.dataHash, event, eventIndex);
+  if (!bytes.ok) return bytes;
+  if (entry?.resource.kind === 'buffer') {
+    const result = context.queue.writeBuffer(entry.resource.value, 0, bytes.value);
+    return result.ok ? ok(undefined) : eventFailure(eventIndex, event, 'write', result.error);
+  }
+  return eventFailure(
+    eventIndex,
+    event,
+    'lookup',
+    'initialData currently requires a buffer resource',
+  );
+}
+
+export function requireResource<T>(
+  context: ReplayExecutionContext,
+  resourceId: string,
+  kind: ReplayResource['kind'] | string,
+  eventIndex: number,
+  eventKind: RhiCallEvent['kind'],
+  role?: string,
+): Result<T, RhiDebugError> {
+  const entry = context.table.get(resourceId);
+  if (
+    entry === undefined ||
+    entry.resource.kind !== kind ||
+    (role !== undefined && entry.resource.role !== role)
+  ) {
+    return missingResource(
+      eventIndex,
+      { kind: eventKind } as RhiCallEvent,
+      resourceId,
+      `${kind}${role === undefined ? '' : `/${role}`}`,
+    );
+  }
+  return ok(entry.resource.value as T);
+}
+
+export function requireReplayResource(
+  context: ReplayExecutionContext,
+  resourceId: string,
+  kind: ReplayResource['kind'] | string,
+  eventIndex: number,
+  eventKind: RhiCallEvent['kind'],
+  role?: string,
+): Result<ReplayResource, RhiDebugError> {
+  const entry = context.table.get(resourceId);
+  if (
+    entry === undefined ||
+    entry.resource.kind !== kind ||
+    (role !== undefined && entry.resource.role !== role)
+  ) {
+    return missingResource(
+      eventIndex,
+      { kind: eventKind } as RhiCallEvent,
+      resourceId,
+      `${kind}${role === undefined ? '' : `/${role}`}`,
+    );
+  }
+  return ok(entry.resource);
+}
+
+export function passCall(
+  context: ReplayExecutionContext,
+  event: RhiCallEvent,
+  eventIndex: number,
+  role: 'render-pass' | 'compute-pass' | 'pass',
+  call: (pass: ReplayPass) => Result<void, RhiDebugError>,
+): Result<void, RhiDebugError> {
+  const passId = 'passHandleId' in event ? event.passHandleId : undefined;
+  if (passId === undefined)
+    return eventFailure(eventIndex, event, 'lookup', 'pass handle is missing');
+  const entry = context.table.get(passId);
+  const valid =
+    entry?.resource.kind === 'encoder' && (role === 'pass' || entry.resource.role === role);
+  if (!valid || entry === undefined || entry.resource.kind !== 'encoder') {
+    return missingResource(eventIndex, event, passId, role);
+  }
+  return call(entry.resource.value as ReplayPass);
+}
+
+export function pipelineError<T>(
+  result: Result<T, RhiDebugError>,
+  event: RhiCallEvent,
+  eventIndex: number,
+): Result<never, RhiDebugError> {
+  return result.ok
+    ? eventFailure(eventIndex, event, 'lookup', 'resource has the wrong role')
+    : result;
+}
+
+export function missingResource(
+  eventIndex: number,
+  event: RhiCallEvent,
+  resourceId: string,
+  expected: string,
+): Result<never, RhiDebugError> {
+  return eventFailure(eventIndex, event, 'lookup', `resource ${resourceId} is not a ${expected}`);
+}
+
+export function unsupportedEvent(
+  eventIndex: number,
+  event: RhiCallEvent,
+  cause: string,
+): Result<never, RhiDebugError> {
+  return eventFailure(eventIndex, event, 'lookup', cause);
+}