@forgeax/engine-rhi-debug 0.1.28 → 0.1.30

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,8 +776,18 @@ 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 timestamp = replayTimestampWrites(context, event, eventIndex);
+  if (!timestamp.ok) return timestamp;
   const descriptor = {
     ...event.desc,
+    ...(timestamp.value === undefined ? {} : { timestampWrites: timestamp.value }),
     colorAttachments: colors,
     ...(depth?.kind === 'texture-view'
       ? {
@@ -684,6 +797,7 @@ function beginRenderPass(
           } as RenderPassDepthStencilAttachment,
         }
       : {}),
+    ...(querySet?.kind === 'query-set' ? { occlusionQuerySet: querySet.value } : {}),
   };
   const pass = encoder.value.beginRenderPass(descriptor as never);
   return context.table.set(
@@ -693,6 +807,29 @@ function beginRenderPass(
   );
 }
 
+function replayTimestampWrites(
+  context: ReplayExecutionContext,
+  event: Extract<RhiCallEvent, { kind: 'beginRenderPass' | 'beginComputePass' }>,
+  eventIndex: number,
+): Result<import('@forgeax/engine-rhi').RenderPassTimestampWrites | undefined, RhiDebugError> {
+  if (event.desc?.timestampWrites === undefined) return ok(undefined);
+  const handle = event.timestampQuerySetHandleId;
+  if (handle === undefined)
+    return missingResource(eventIndex, event, 'timestamp-query-set', 'query-set');
+  const query = requireResource<import('@forgeax/engine-rhi').QuerySet>(
+    context,
+    handle,
+    'query-set',
+    eventIndex,
+    event.kind,
+  );
+  if (!query.ok) return query;
+  return ok({
+    ...event.desc.timestampWrites,
+    querySet: query.value,
+  });
+}
+
 function beginComputePass(
   context: ReplayExecutionContext,
   event: Extract<RhiCallEvent, { kind: 'beginComputePass' }>,
@@ -707,7 +844,12 @@ function beginComputePass(
     'command',
   );
   if (!encoder.ok) return encoder;
-  const pass = encoder.value.beginComputePass(JSON.parse(JSON.stringify(event.desc)));
+  const timestamp = replayTimestampWrites(context, event, eventIndex);
+  if (!timestamp.ok) return timestamp;
+  const pass = encoder.value.beginComputePass({
+    ...(event.desc?.label === undefined ? {} : { label: event.desc.label }),
+    ...(timestamp.value === undefined ? {} : { timestampWrites: timestamp.value }),
+  });
   return context.table.set(
     event.passHandleId,
     { kind: 'encoder', role: 'compute-pass', value: pass },

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'),
   });
 }
 
@@ -168,6 +173,13 @@ async function readTexture(
   const format = stringField(descriptor, 'format');
   const dimension = stringField(descriptor, 'dimension') ?? '2d';
   if (format === undefined) return readbackFailure(`texture ${resourceId} has no recorded format`);
+  if ((numberField(descriptor, 'sampleCount') ?? 1) > 1) {
+    return readbackUnsupported(
+      resourceId,
+      format,
+      'multisampled textures require a single-sample resolve target before readback',
+    );
+  }
   const plan = getTextureReadbackPlan({ format, dimension });
   if (!plan.supported) {
     return err(

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);

package/src/replay/session.ts

@@ -1,4 +1,5 @@
 import type {
+  MappedBuffer,
   RhiCommandEncoder,
   RhiComputePassEncoder,
   RhiDevice,
@@ -69,6 +70,18 @@ export interface ReplaySession {
     subresource?: ReadbackSubresource,
     signal?: AbortSignal,
   ): Promise<Result<ReplayReadbackResult, RhiDebugError>>;
+  /**
+   * Replay the captured stream through one indexed work item, then read the
+   * resource from that exact post-work state.  Unlike readResource(), this is
+   * not a bootstrap-only read and therefore can inspect compute/storage
+   * outputs produced by the selected work without creating a second tape.
+   */
+  readResourceAtWork(
+    resourceId: string,
+    workIndex: number,
+    subresource?: ReadbackSubresource,
+    signal?: AbortSignal,
+  ): Promise<Result<ReplayReadbackResult, RhiDebugError>>;
   dispose(): Promise<Result<void, RhiDebugError>>;
 }
 
@@ -204,6 +217,42 @@ export async function openReplay(
         backend.createShaderModule,
       );
     },
+    async readResourceAtWork(resourceId, workIndex, subresource, signal) {
+      if (disposed) return positionError(workIndex, index.works.length);
+      if (signal?.aborted) {
+        return err(
+          createRhiDebugError('readback-failed', {
+            stage: 'readback',
+            cause: 'readback was aborted',
+          }),
+        );
+      }
+      const work = index.works[workIndex];
+      if (work === undefined || model.works[workIndex] === undefined) {
+        return positionError(workIndex, index.works.length);
+      }
+      const cleared = await reset();
+      if (!cleared.ok) return cleared;
+      const bootstrapped = await prepare();
+      if (!bootstrapped.ok) return bootstrapped;
+      const replayed = await replayThroughWork(context, index, work, signal);
+      if (!replayed.ok) return replayed;
+      const read = await readReplayResource(
+        backend.device,
+        table,
+        resourceId,
+        subresource,
+        backend.createShaderModule,
+      );
+      if (!read.ok) return read;
+      return ok({
+        ...read.value,
+        provenance: {
+          ...read.value.provenance,
+          selectedWorkIndex: work.workIndex,
+        },
+      });
+    },
     async dispose() {
       if (disposed) return ok(undefined);
       const result = table.dispose();
@@ -328,7 +377,14 @@ async function executeBootstrapResource(
   bootstrapIndex: number,
 ): Promise<Result<void, RhiDebugError>> {
   const event: RhiCallEvent = JSON.parse(JSON.stringify(resource.create));
-  const result = await executeEvent(context, event, -bootstrapIndex - 1);
+  // Captured GPU-written buffers need not allow COPY_DST. Restore their
+  // initial bytes through creation mapping, which is legal for every usage
+  // (including MAP_WRITE, where adding COPY_DST would itself be invalid).
+  const replayEvent =
+    event.kind === 'createBuffer' && resource.initialData.length > 0
+      ? { ...event, desc: { ...event.desc, mappedAtCreation: true } }
+      : event;
+  const result = await executeEvent(context, replayEvent, -bootstrapIndex - 1);
   return result;
 }
 
@@ -351,25 +407,50 @@ async function seedBootstrapResource(
       'bootstrap initialData requires a buffer or color texture resource',
     );
   }
-  for (const slice of resource.initialData) {
-    const blob = context.tape.blobs.find((candidate) => candidate.hash === slice.hash);
-    if (blob === undefined) {
-      return eventFailure(-bootstrapIndex - 1, event, 'lookup', `blob ${slice.hash} is missing`);
-    }
-    const end = slice.byteOffset + slice.byteLength;
-    if (slice.byteOffset < 0 || slice.byteLength < 0 || end > blob.bytes.byteLength) {
-      return eventFailure(
-        -bootstrapIndex - 1,
-        event,
-        'lookup',
-        `blob ${slice.hash} does not contain initialData slice [${slice.byteOffset}, ${end})`,
-      );
-    }
-    const bytes = blob.bytes.slice(slice.byteOffset, slice.byteOffset + slice.byteLength);
-    const written = context.queue.writeBuffer(entry.resource.value, 0, bytes);
-    if (!written.ok) {
-      return eventFailure(-bootstrapIndex - 1, event, 'write', written.error);
+  // executeBootstrapResource created this buffer mapped specifically for
+  // restoration. It must be unmapped before any recorded work can consume it.
+  const mapped = entry.resource.value as MappedBuffer;
+  // RhiNull deliberately exposes opaque structural handles rather than a
+  // CPU-visible mapping implementation. Its replay bytes have no observable
+  // storage, so there is nothing to seed; real backends always provide the
+  // MappedBuffer methods below and still take the strict mapping path.
+  if (
+    typeof (mapped as Partial<MappedBuffer>).getMappedRange !== 'function' ||
+    typeof (mapped as Partial<MappedBuffer>).unmap !== 'function'
+  ) {
+    if (context.device.caps.backendKind === 'null') return ok(undefined);
+    return eventFailure(
+      -bootstrapIndex - 1,
+      event,
+      'write',
+      'bootstrap buffer mapping is unavailable on the replay backend',
+    );
+  }
+  try {
+    const range = mapped.getMappedRange();
+    if (!range.ok) return eventFailure(-bootstrapIndex - 1, event, 'write', range.error);
+    const target = new Uint8Array(range.value);
+    for (const slice of resource.initialData) {
+      const blob = context.tape.blobs.find((candidate) => candidate.hash === slice.hash);
+      if (blob === undefined) {
+        return eventFailure(-bootstrapIndex - 1, event, 'lookup', `blob ${slice.hash} is missing`);
+      }
+      const end = slice.byteOffset + slice.byteLength;
+      if (slice.byteOffset < 0 || slice.byteLength < 0 || end > blob.bytes.byteLength) {
+        return eventFailure(
+          -bootstrapIndex - 1,
+          event,
+          'lookup',
+          `blob ${slice.hash} does not contain initialData slice [${slice.byteOffset}, ${end})`,
+        );
+      }
+      if (slice.byteLength > target.byteLength) {
+        return eventFailure(-bootstrapIndex - 1, event, 'write', 'initialData exceeds buffer size');
+      }
+      target.set(blob.bytes.subarray(slice.byteOffset, end));
     }
+  } finally {
+    mapped.unmap();
   }
   return ok(undefined);
 }
@@ -489,12 +570,8 @@ async function finalizeWorkPass(
       `pass ${begin.passHandleId} is not open`,
     );
   }
-  try {
-    (entry.resource.value as RhiRenderPassEncoder | RhiComputePassEncoder).end();
-  } catch (cause) {
-    return eventFailure(pass.endEventIndex ?? work.eventIndex, begin, 'encode', cause);
-  }
-  context.table.delete(begin.passHandleId);
+  const closed = closeReplayPass(context, entry, begin, pass, work.eventIndex);
+  if (!closed.ok) return closed;
   const finishEventIndex = findNextEvent(
     context.tape.events,
     pass.beginEventIndex,
@@ -510,6 +587,13 @@ async function finalizeWorkPass(
       `encoder ${begin.cmdHandleId} is not available`,
     );
   }
+  const closure = await replayCommandClosure(
+    context,
+    begin.cmdHandleId,
+    (pass.endEventIndex ?? work.eventIndex) + 1,
+    finishEventIndex ?? context.tape.events.length,
+  );
+  if (!closure.ok) return closure;
   const finished = (encoder.resource.value as RhiCommandEncoder).finish();
   const finishEvent = context.tape.events[finishEventIndex ?? work.eventIndex] ?? begin;
   if (!finished.ok)
@@ -538,6 +622,131 @@ async function finalizeWorkPass(
   return ok(undefined);
 }
 
+function closeReplayPass(
+  context: ReplayExecutionContext,
+  entry: NonNullable<ReturnType<ReplayExecutionContext['table']['get']>>,
+  begin: Extract<RhiCallEvent, { kind: 'beginRenderPass' | 'beginComputePass' }>,
+  pass: TapeIndex['passes'][number],
+  selectedEventIndex: number,
+): Result<void, RhiDebugError> {
+  const activeQuery = activeOcclusionQuery(
+    context.tape.events,
+    begin.kind === 'beginRenderPass' ? begin.passHandleId : undefined,
+    pass.beginEventIndex,
+    selectedEventIndex,
+  );
+  if (!activeQuery.ok) return activeQuery;
+  try {
+    if (activeQuery.value !== undefined) {
+      if (entry.resource.role !== 'render-pass') {
+        return eventFailure(
+          activeQuery.value.eventIndex,
+          activeQuery.value.event,
+          'lookup',
+          'an active occlusion query belongs to a non-render pass',
+        );
+      }
+      const endedQuery = (entry.resource.value as RhiRenderPassEncoder).endOcclusionQuery();
+      if (!endedQuery.ok) {
+        return eventFailure(
+          activeQuery.value.eventIndex,
+          activeQuery.value.event,
+          'encode',
+          endedQuery.error,
+        );
+      }
+    }
+    (entry.resource.value as RhiRenderPassEncoder | RhiComputePassEncoder).end();
+  } catch (cause) {
+    return eventFailure(pass.endEventIndex ?? selectedEventIndex, begin, 'encode', cause);
+  }
+  context.table.delete(begin.passHandleId);
+  return ok(undefined);
+}
+
+async function replayCommandClosure(
+  context: ReplayExecutionContext,
+  cmdHandleId: string,
+  start: number,
+  end: number,
+): Promise<Result<void, RhiDebugError>> {
+  for (let eventIndex = start; eventIndex < end; eventIndex++) {
+    const event = context.tape.events[eventIndex];
+    if (event === undefined || !isCommandClosureEvent(event)) continue;
+    if (event.cmdHandleId !== cmdHandleId) continue;
+    const result = await executeEvent(context, event, eventIndex);
+    if (!result.ok) return result;
+  }
+  return ok(undefined);
+}
+
+type ActiveOcclusionQuery = Extract<RhiCallEvent, { kind: 'beginOcclusionQuery' }>;
+
+function activeOcclusionQuery(
+  events: readonly RhiCallEvent[],
+  passHandleId: string | undefined,
+  beginEventIndex: number,
+  selectedEventIndex: number,
+): Result<
+  { readonly eventIndex: number; readonly event: ActiveOcclusionQuery } | undefined,
+  RhiDebugError
+> {
+  if (passHandleId === undefined) return ok(undefined);
+  let active: { readonly eventIndex: number; readonly event: ActiveOcclusionQuery } | undefined;
+  for (let eventIndex = beginEventIndex + 1; eventIndex <= selectedEventIndex; eventIndex++) {
+    const event = events[eventIndex];
+    if (event === undefined || !('passHandleId' in event) || event.passHandleId !== passHandleId)
+      continue;
+    if (event.kind === 'beginOcclusionQuery') {
+      if (active !== undefined) {
+        return eventFailure(
+          eventIndex,
+          event,
+          'encode',
+          'an occlusion query is already active for this render pass',
+        );
+      }
+      active = { eventIndex, event };
+    } else if (event.kind === 'endOcclusionQuery') {
+      if (active === undefined) {
+        return eventFailure(
+          eventIndex,
+          event,
+          'encode',
+          'an occlusion query ended without a matching begin',
+        );
+      }
+      active = undefined;
+    }
+  }
+  return ok(active);
+}
+
+function isCommandClosureEvent(event: RhiCallEvent): event is Extract<
+  RhiCallEvent,
+  {
+    kind:
+      | 'resolveQuerySet'
+      | 'copyBufferToBuffer'
+      | 'copyBufferToTexture'
+      | 'copyTextureToBuffer'
+      | 'copyTextureToTexture'
+      | 'clearBuffer';
+  }
+> {
+  switch (event.kind) {
+    case 'resolveQuerySet':
+    case 'copyBufferToBuffer':
+    case 'copyBufferToTexture':
+    case 'copyTextureToBuffer':
+    case 'copyTextureToTexture':
+    case 'clearBuffer':
+      return true;
+    default:
+      return false;
+  }
+}
+
 function findNextEvent(
   events: readonly RhiCallEvent[],
   start: number,
@@ -578,9 +787,14 @@ async function readWorkAttachment(
       }),
     );
   }
-  const viewId = begin.colorAttachmentViewHandleIds.find(
-    (candidate): candidate is string => candidate !== undefined,
+  const attachmentIndex = begin.colorAttachmentViewHandleIds.findIndex(
+    (candidate) => candidate !== undefined,
   );
+  // finalizeWorkPass has ended the pass and resolved the selected work.
+  // Keep the resolve target paired with its color slot, including sparse MRTs.
+  const viewId =
+    begin.colorAttachmentResolveTargetHandleIds?.[attachmentIndex] ??
+    begin.colorAttachmentViewHandleIds[attachmentIndex];
   if (viewId === undefined) {
     return err(
       createRhiDebugError('readback-unsupported', {