@forgeax/engine-rhi-debug 0.1.27 → 0.1.29

package/src/recorder/proxy.ts

@@ -3,6 +3,7 @@ import { err, ok, type Result } from '@forgeax/engine-types';
 import { createRhiDebugError, type RhiDebugError } from '../errors';
 import {
   type CreateShaderModuleFn,
+  type CreateShaderModuleImmediateFn,
   type DebugRhiInstance,
   wrap,
   wrapCreateShaderModule,
@@ -15,6 +16,8 @@ export interface RecordableBackend {
     ) => Result<RhiCanvasContext, RhiError>;
   };
   readonly createShaderModule: CreateShaderModuleFn;
+  /** Optional synchronous factory retained for render's first-use path. */
+  readonly createShaderModuleImmediate?: CreateShaderModuleImmediateFn;
 }
 
 export interface RecorderBackend extends RecordableBackend {
@@ -29,21 +32,74 @@ export interface RecorderProxy {
 export function createRecorderProxy(backend: RecordableBackend): RecorderProxy {
   const recorder = wrap(backend.rhi);
   const wrappedCreateShaderModule = wrapCreateShaderModule(backend.createShaderModule, recorder);
+  const originalCreateShaderModuleImmediate = backend.createShaderModuleImmediate;
+  const wrappedCreateShaderModuleImmediate =
+    originalCreateShaderModuleImmediate === undefined
+      ? undefined
+      : (device: RhiDevice, desc: { code: string; label?: string | undefined }) => {
+          const realDevice =
+            (device as RhiDevice & { readonly _realDevice?: RhiDevice })._realDevice ?? device;
+          const result = originalCreateShaderModuleImmediate(realDevice, desc);
+          if (!result.ok) return result;
+          const hId = recorder.pushExternalCreateEvent(result.value, 'shaderModule', {
+            kind: 'createShaderModule',
+            handleId: '' as import('../types').HandleId,
+            wgslCode: desc.code,
+          });
+          recorder.registerShaderModule(result.value, hId);
+          return result;
+        };
   const acquireCanvasContext = backend.rhi.acquireCanvasContext;
   // Runtime's explicit-RHI seam receives the wrapped singleton as one value.
   // Keep the standalone shader factory enumerable on that value so the
   // renderer can preserve the complete typed backend pack after capture
   // attachment; the public RhiInstance contract remains unchanged.
-  const rhi: RecordableBackend['rhi'] & { readonly createShaderModule: CreateShaderModuleFn } = {
+  const rhi: RecordableBackend['rhi'] & {
+    readonly createShaderModule: CreateShaderModuleFn;
+    readonly createShaderModuleImmediate?: CreateShaderModuleImmediateFn;
+  } = {
     requestAdapter: recorder.requestAdapter.bind(recorder),
     createShaderModule: wrappedCreateShaderModule,
+    ...(wrappedCreateShaderModuleImmediate === undefined
+      ? {}
+      : { createShaderModuleImmediate: wrappedCreateShaderModuleImmediate }),
     ...(acquireCanvasContext === undefined
       ? {}
-      : { acquireCanvasContext: acquireCanvasContext.bind(backend.rhi) }),
+      : {
+          acquireCanvasContext(canvas) {
+            const result = acquireCanvasContext.call(backend.rhi, canvas);
+            if (!result.ok) return result;
+            const context = result.value;
+            // rhi-webgpu's canvas shim translates the forgeax RhiDevice to the
+            // native GPUDevice through its own WeakMap. The recorder device is
+            // an intentional proxy, so passing it directly makes configure()
+            // reject with a foreign-device error before the first frame. Keep
+            // the context owned by the selected backend, but unwrap only the
+            // device argument at this boundary; all resource calls continue to
+            // flow through the recorder device and remain capturable.
+            return ok({
+              ...context,
+              configure(configuration) {
+                const device = (
+                  configuration.device as RhiDevice & {
+                    readonly _realDevice?: RhiDevice;
+                  }
+                )._realDevice;
+                return context.configure({
+                  ...configuration,
+                  ...(device === undefined ? {} : { device }),
+                });
+              },
+            });
+          },
+        }),
   };
   const wrappedBackend: RecorderBackend = {
     rhi,
     createShaderModule: wrappedCreateShaderModule,
+    ...(wrappedCreateShaderModuleImmediate === undefined
+      ? {}
+      : { createShaderModuleImmediate: wrappedCreateShaderModuleImmediate }),
     unwrapDeviceForSurface(device) {
       const raw = (device as RhiDevice & { readonly _realDevice?: RhiDevice })._realDevice;
       if (raw !== undefined) return ok(raw);

package/src/recorder/session.ts

@@ -147,6 +147,6 @@ export function attachRecorder(
   return ok(attachment);
 }
 
-export type { CreateShaderModuleFn } from '../recorder';
+export type { CreateShaderModuleFn, CreateShaderModuleImmediateFn } from '../recorder';
 export type { EncodedTape } from './assemble';
 export type { RecordableBackend, RecorderBackend } from './proxy';

package/src/recorder/shader.ts

@@ -2,7 +2,24 @@
 
 import type { Result, RhiDevice, ShaderModule } from '@forgeax/engine-rhi';
 import type { HandleId } from '../types';
-import type { CreateShaderModuleFn, DebugRhiInstance } from './core';
+import type { CreateShaderModuleFn, CreateShaderModuleImmediateFn, DebugRhiInstance } from './core';
+
+function recordShaderModule(
+  debugInst: DebugRhiInstance,
+  result: Result<ShaderModule, import('@forgeax/engine-rhi').RhiError>,
+  desc: { code: string; label?: string | undefined },
+): Result<ShaderModule, import('@forgeax/engine-rhi').RhiError> {
+  if (!result.ok) return result;
+  const hId = debugInst.pushExternalCreateEvent(result.value, 'shaderModule', {
+    kind: 'createShaderModule',
+    handleId: '' as HandleId,
+    wgslCode: desc.code,
+  });
+  // Register the shader module handle in the recorder's handleMap so
+  // downstream pipeline events can resolve the handleId during replay.
+  debugInst.registerShaderModule(result.value, hId);
+  return result;
+}
 
 export function wrapCreateShaderModule(
   originalFn: CreateShaderModuleFn,
@@ -21,27 +38,17 @@ export function wrapCreateShaderModule(
     // proxyDevice exposes for exactly this purpose.
     const realDevice = (device as RhiDevice & { _realDevice?: RhiDevice })._realDevice ?? device;
     const result = await originalFn(realDevice, desc);
-    if (!result.ok) return result;
-
-    // I-12 (round 1 implement-review) fix: route the createShaderModule
-    // event through the same `pushExternalEvent` helper that wraps the
-    // internal `pushEvent` (and therefore the `_skipRecord` + state-machine
-    // guard). The previous `(events as RhiCallEvent[]).push(...)` cast
-    // bypassed those guards — recorder-internal RHI calls during shader
-    // construction would have self-polluted the tape.
-    const hId = debugInst.pushExternalCreateEvent(result.value, 'shaderModule', {
-      kind: 'createShaderModule',
-      handleId: '' as HandleId,
-      wgslCode: desc.code,
-    });
-    // Register the shader module handle in the recorder's handleMap so
-    // downstream pipeline events (createRenderPipeline / createComputePipeline)
-    // can resolve the handleId via getHandleId. Required for cross-device
-    // replay: the tape's pipeline desc carries live GPU module objects which
-    // are device-bound, so the replayer must swap them with re-created shader
-    // modules from the handleMap using the handleId.
-    debugInst.registerShaderModule(result.value, hId);
+    return recordShaderModule(debugInst, result, desc);
+  };
+}
 
-    return result;
+/** Wrap the synchronous render-path factory while preserving tape ownership. */
+export function wrapCreateShaderModuleImmediate(
+  originalFn: CreateShaderModuleImmediateFn,
+  debugInst: DebugRhiInstance,
+): CreateShaderModuleImmediateFn {
+  return (device, desc) => {
+    const realDevice = (device as RhiDevice & { _realDevice?: RhiDevice })._realDevice ?? device;
+    return recordShaderModule(debugInst, originalFn(realDevice, desc), desc);
   };
 }

package/src/recorder.ts

@@ -1,6 +1,10 @@
 // @forgeax/engine-rhi-debug/src/recorder -- split recorder public seam.
 
-export type { CreateShaderModuleFn, DebugRhiInstance } from './recorder/core';
+export type {
+  CreateShaderModuleFn,
+  CreateShaderModuleImmediateFn,
+  DebugRhiInstance,
+} from './recorder/core';
 export { PER_EVENT_OVERHEAD, TAPE_FORMAT_VERSION } from './recorder/core';
 export type {
   CaptureFrameOptions,
@@ -11,5 +15,5 @@ export type {
   RecorderOptions,
 } from './recorder/session';
 export { attachRecorder } from './recorder/session';
-export { wrapCreateShaderModule } from './recorder/shader';
+export { wrapCreateShaderModule, wrapCreateShaderModuleImmediate } from './recorder/shader';
 export { wrap } from './recorder/wrap';

package/src/replay/execute.ts

@@ -10,6 +10,7 @@ import type {
   RhiDevice,
   RhiError,
   RhiQueue,
+  RhiRenderPipelineOps,
   Texture,
 } from '@forgeax/engine-rhi';
 import { ok, type Result } from '@forgeax/engine-types';
@@ -70,10 +71,20 @@ export async function executeEvent(
             kind: 'texture',
           },
         );
+      case 'createQuerySet':
+        return createResource(
+          context,
+          eventIndex,
+          event,
+          context.device.createQuerySet(event.desc),
+          { kind: 'query-set' },
+        );
       case 'destroyBuffer':
         return destroyResource(context, eventIndex, event, 'buffer');
       case 'destroyTexture':
         return destroyResource(context, eventIndex, event, 'texture');
+      case 'destroyQuerySet':
+        return destroyQuerySet(context, event, eventIndex);
       case 'createTextureView': {
         const texture = requireResource<Texture>(
           context,
@@ -110,6 +121,28 @@ export async function executeEvent(
           context.device.createBindGroupLayout(event.desc as never),
           { kind: 'binding', role: 'bind-group-layout' },
         );
+      case 'getBindGroupLayout': {
+        const pipeline = requireReplayResource(
+          context,
+          event.pipelineHandleId,
+          'pipeline',
+          eventIndex,
+          event.kind,
+        );
+        if (!pipeline.ok) return pipeline;
+        return createResource(
+          context,
+          eventIndex,
+          event,
+          ok(
+            (
+              pipeline.value.value as import('@forgeax/engine-rhi').RenderPipeline &
+                RhiRenderPipelineOps
+            ).getBindGroupLayout(event.index),
+          ),
+          { kind: 'binding', role: 'bind-group-layout' },
+        );
+      }
       case 'createBindGroup':
         return createBindGroup(context, event, eventIndex);
       case 'createPipelineLayout':
@@ -141,6 +174,22 @@ export async function executeEvent(
         return beginRenderPass(context, event, eventIndex);
       case 'beginComputePass':
         return beginComputePass(context, event, eventIndex);
+      case 'resolveQuerySet':
+        return resolveQuerySet(context, event, eventIndex);
+      case 'beginOcclusionQuery':
+        return passCall(context, event, eventIndex, 'render-pass', (pass) => {
+          const result = pass.beginOcclusionQuery(event.queryIndex);
+          return result.ok
+            ? ok(undefined)
+            : eventFailure(eventIndex, event, 'encode', result.error);
+        });
+      case 'endOcclusionQuery':
+        return passCall(context, event, eventIndex, 'render-pass', (pass) => {
+          const result = pass.endOcclusionQuery();
+          return result.ok
+            ? ok(undefined)
+            : eventFailure(eventIndex, event, 'encode', result.error);
+        });
       case 'copyBufferToBuffer':
         return copyBufferToBuffer(context, event, eventIndex);
       case 'copyBufferToTexture':
@@ -386,6 +435,60 @@ function destroyResource(
   return ok(undefined);
 }
 
+function destroyQuerySet(
+  context: ReplayExecutionContext,
+  event: Extract<RhiCallEvent, { kind: 'destroyQuerySet' }>,
+  eventIndex: number,
+): Result<void, RhiDebugError> {
+  const entry = context.table.get(event.handleId);
+  if (entry?.resource.kind !== 'query-set')
+    return missingResource(eventIndex, event, event.handleId, 'query-set');
+  const result = context.device.destroyQuerySet(entry.resource.value);
+  if (!result.ok) return eventFailure(eventIndex, event, 'create', result.error);
+  context.table.delete(event.handleId);
+  return ok(undefined);
+}
+
+function resolveQuerySet(
+  context: ReplayExecutionContext,
+  event: Extract<RhiCallEvent, { kind: 'resolveQuerySet' }>,
+  eventIndex: number,
+): Result<void, RhiDebugError> {
+  const encoder = requireResource<RhiCommandEncoder>(
+    context,
+    event.cmdHandleId,
+    'encoder',
+    eventIndex,
+    event.kind,
+    'command',
+  );
+  const querySet = requireResource<import('@forgeax/engine-rhi').QuerySet>(
+    context,
+    event.querySetHandleId,
+    'query-set',
+    eventIndex,
+    event.kind,
+  );
+  const destination = requireResource<Buffer>(
+    context,
+    event.destinationHandleId,
+    'buffer',
+    eventIndex,
+    event.kind,
+  );
+  if (!encoder.ok) return encoder;
+  if (!querySet.ok) return querySet;
+  if (!destination.ok) return destination;
+  const result = encoder.value.resolveQuerySet(
+    querySet.value,
+    event.firstQuery,
+    event.queryCount,
+    destination.value,
+    event.destinationOffset,
+  );
+  return result.ok ? ok(undefined) : eventFailure(eventIndex, event, 'encode', result.error);
+}
+
 async function createShaderModule(
   context: ReplayExecutionContext,
   event: Extract<RhiCallEvent, { kind: 'createShaderModule' }>,
@@ -673,6 +776,13 @@ function beginRenderPass(
     event.depthStencilViewHandleId === undefined
       ? undefined
       : context.table.get(event.depthStencilViewHandleId)?.resource;
+  const querySet =
+    event.occlusionQuerySetHandleId === undefined
+      ? undefined
+      : context.table.get(event.occlusionQuerySetHandleId)?.resource;
+  if (event.occlusionQuerySetHandleId !== undefined && querySet?.kind !== 'query-set') {
+    return missingResource(eventIndex, event, event.occlusionQuerySetHandleId, 'query-set');
+  }
   const descriptor = {
     ...event.desc,
     colorAttachments: colors,
@@ -684,6 +794,7 @@ function beginRenderPass(
           } as RenderPassDepthStencilAttachment,
         }
       : {}),
+    ...(querySet?.kind === 'query-set' ? { occlusionQuerySet: querySet.value } : {}),
   };
   const pass = encoder.value.beginRenderPass(descriptor as never);
   return context.table.set(

package/src/replay/readback.ts

@@ -100,7 +100,7 @@ function resolveTextureViewSubresource(
   source: ResourceTableEntry,
   requested: ReplayReadbackRequest | undefined,
 ): Result<ReplayReadbackRequest | undefined, RhiDebugError> {
-  if (requested === undefined || isBufferRange(requested)) return ok(requested);
+  if (isBufferRange(requested)) return ok(requested);
   const sourceDescriptor = recordField(source.descriptor, 'desc');
   const sourceSize = textureSize(sourceDescriptor?.size);
   const sourceMipCount = numberField(sourceDescriptor, 'mipLevelCount') ?? 1;
@@ -112,8 +112,8 @@ function resolveTextureViewSubresource(
   const arrayLayerCount =
     numberField(viewDescriptor, 'arrayLayerCount') ??
     sourceSize.depthOrArrayLayers - baseArrayLayer;
-  const localMipLevel = requested.mipLevel ?? 0;
-  const localArrayLayer = requested.arrayLayer ?? 0;
+  const localMipLevel = requested?.mipLevel ?? 0;
+  const localArrayLayer = requested?.arrayLayer ?? 0;
   if (
     !validIndex(baseMipLevel, sourceMipCount + 1) ||
     !validIndex(baseArrayLayer, sourceSize.depthOrArrayLayers + 1) ||
@@ -128,6 +128,11 @@ function resolveTextureViewSubresource(
     ...requested,
     mipLevel: baseMipLevel + localMipLevel,
     arrayLayer: baseArrayLayer + localArrayLayer,
+    aspect:
+      requested?.aspect ??
+      (viewDescriptor?.aspect === 'depth-only' || viewDescriptor?.aspect === 'stencil-only'
+        ? viewDescriptor.aspect
+        : 'all'),
   });
 }
 

package/src/replay/resources.ts

@@ -5,6 +5,7 @@ import type {
   CommandBuffer,
   ComputePipeline,
   PipelineLayout,
+  QuerySet,
   RenderPipeline,
   RhiCommandEncoder,
   RhiComputePassEncoder,
@@ -24,6 +25,7 @@ export type ReplayResource = {
 } & (
   | { readonly kind: 'buffer'; readonly value: Buffer }
   | { readonly kind: 'texture'; readonly value: Texture }
+  | { readonly kind: 'query-set'; readonly value: QuerySet }
   | { readonly kind: 'texture-view'; readonly value: TextureView }
   | { readonly kind: 'sampler'; readonly value: Sampler }
   | { readonly kind: 'shader-module'; readonly value: ShaderModule }
@@ -132,6 +134,10 @@ export class ResourceTable {
         const result = this.device.destroyTexture(entry.resource.value);
         if (!result.ok && firstFailure === undefined)
           firstFailure = resourceDisposeFailure(entry.resourceId, result.error.code);
+      } else if (entry.resource.kind === 'query-set') {
+        const result = this.device.destroyQuerySet(entry.resource.value);
+        if (!result.ok && firstFailure === undefined)
+          firstFailure = resourceDisposeFailure(entry.resourceId, result.error.code);
       }
     }
     return firstFailure ?? ok(undefined);