@forgeax/engine-rhi-debug 0.1.29 → 0.1.30

package/README.md

@@ -108,20 +108,23 @@ views aligned.
 
 ## Replay and readback
 
+`openReplay(tape, backend)` uses the caller's fresh device and shader factory.
+`ResourceTable` owns replay resources and typed handle generations; stale
+generations fail closed. Session disposal releases replay resources; the
+supplied backend remains owned by its caller.
+
+`inspectWork(..., ['pixels'])` reads the first color attachment's resolve target
+when present, after finishing the selected work's pass. Direct reads of an
+unresolved multisampled texture return `readback-unsupported` before any copy.
+The remaining readback matrix is explicit: supported color/depth formats use
+the backend path, unsupported formats return `readback-unsupported`, and
+transfer or map failures return `readback-failed`.
 `readResource(resourceId, subresource)` reads the captured initial state.
 `readResourceAtWork(resourceId, workIndex, subresource)` replays through the
 selected work before reading, including compute storage outputs. Its
 `provenance.selectedWorkIndex` identifies that post-work state. Use this form
 when checking what a dispatch produced; initial bytes are not output evidence.
 
-`openReplay` requires a `ReplayBackend` factory. The factory is called only for
-the requested operation and must return a fresh backend. `ResourceTable` owns
-typed handle generations and disposal; stale generations fail closed. The
-readback matrix is explicit: supported color/depth formats use the backend
-path, unsupported formats return `readback-unsupported`, and transfer or map
-failures return `readback-failed`. Every successful session and every failed
-setup path releases backend resources before returning.
-
 ## Structured errors
 
 The public operation boundary uses `RhiDebugError`. Consumers should narrow
@@ -189,3 +192,12 @@ FORGEAX_SKIP_HARNESS_SYNC=1 pnpm --filter @forgeax/engine-rhi-debug build
 Browser and Dawn gates belong to the host and application packages. They must
 exercise the same `.rhitape` bytes and the same `workIndex` used by offline
 inspection.
+
+### Timestamp-bearing frame capture
+
+Render, compute and empty-compute pass timestamps retain their QuerySet handle
+identity in v7 events. Capture closure includes a QuerySet created before the
+capture window; validation and resource lineage treat it as a referenced
+resource. Replay replaces its serialized descriptor object with the fresh
+device's QuerySet while preserving beginning/end indices. A missing identity
+is a structured replay failure, never a request to silently remove timestamps.

package/dist/__tests__/timestamp-query-capture.dawn.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=timestamp-query-capture.dawn.test.d.ts.map

package/dist/__tests__/timestamp-query-capture.dawn.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp-query-capture.dawn.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/timestamp-query-capture.dawn.test.ts"],"names":[],"mappings":""}

package/dist/index.mjs

@@ -4433,6 +4433,7 @@ function referencedHandles(event) {
     "pipelineHandleId",
     "querySetHandleId",
     "occlusionQuerySetHandleId",
+    "timestampQuerySetHandleId",
     "indexBufferHandleId",
     "vertexBufferHandleId"
   ];
@@ -5340,6 +5341,7 @@ function eventResources(event) {
         reads: handleRefs(event, [
           "cmdHandleId",
           "occlusionQuerySetHandleId",
+          "timestampQuerySetHandleId",
           "colorAttachmentViewHandleIds",
           "colorAttachmentResolveTargetHandleIds",
           "depthStencilViewHandleId"
@@ -5347,7 +5349,11 @@ function eventResources(event) {
         destroyed: []
       };
     case "beginComputePass":
-      return { created: [event.passHandleId], reads: [event.cmdHandleId], destroyed: [] };
+      return {
+        created: [event.passHandleId],
+        reads: handleRefs(event, ["cmdHandleId", "timestampQuerySetHandleId"]),
+        destroyed: []
+      };
     case "endRenderPass":
     case "endComputePass":
       return { created: [], reads: [event.passHandleId], destroyed: [event.passHandleId] };
@@ -6310,11 +6316,13 @@ function _collectFrameReferencedHandleIds(events) {
         }
         if (we.depthStencilViewHandleId !== void 0) refs.add(we.depthStencilViewHandleId);
         if (we.occlusionQuerySetHandleId !== void 0) refs.add(we.occlusionQuerySetHandleId);
+        if (we.timestampQuerySetHandleId !== void 0) refs.add(we.timestampQuerySetHandleId);
         break;
       }
       case "beginComputePass": {
         const we = e;
         refs.add(we.cmdHandleId);
+        if (we.timestampQuerySetHandleId !== void 0) refs.add(we.timestampQuerySetHandleId);
         break;
       }
       case "finish": {
@@ -6948,12 +6956,13 @@ function createCommandEncoderProxy(s, realEnc, cmdHId) {
         kind: "beginRenderPass",
         cmdHandleId: cmdHId,
         passHandleId: passHId,
+        timestampQuerySetHandleId: desc?.timestampWrites === void 0 ? void 0 : getHandleId(s, desc.timestampWrites.querySet, "querySet"),
         desc: {
           colorAttachments: Array.from(desc.colorAttachments).map(
             (attachment) => attachment === null || attachment === void 0 ? attachment : { ...attachment }
           ),
           ...desc.depthStencilAttachment === void 0 ? {} : { depthStencilAttachment: { ...desc.depthStencilAttachment } },
-          ...desc.timestampWrites === void 0 ? {} : { timestampWrites: desc.timestampWrites },
+          ...desc.timestampWrites === void 0 ? {} : { timestampWrites: recordTimestampWrites(desc.timestampWrites) },
           ...desc.maxDrawCount === void 0 ? {} : { maxDrawCount: desc.maxDrawCount }
         },
         colorAttachmentViewHandleIds,
@@ -6976,7 +6985,11 @@ function createCommandEncoderProxy(s, realEnc, cmdHId) {
         kind: "beginComputePass",
         cmdHandleId: cmdHId,
         passHandleId: passHId,
-        desc
+        timestampQuerySetHandleId: desc?.timestampWrites === void 0 ? void 0 : getHandleId(s, desc.timestampWrites.querySet, "querySet"),
+        desc: desc === void 0 ? void 0 : {
+          ...desc.label === void 0 ? {} : { label: desc.label },
+          timestampWrites: recordTimestampWrites(desc.timestampWrites)
+        }
       });
       const realPass = realEnc.beginComputePass(desc);
       return createComputePassProxy(s, realPass, passHId);
@@ -6987,7 +7000,11 @@ function createCommandEncoderProxy(s, realEnc, cmdHId) {
         kind: "beginComputePass",
         cmdHandleId: cmdHId,
         passHandleId: passHId,
-        desc
+        timestampQuerySetHandleId: desc?.timestampWrites === void 0 ? void 0 : getHandleId(s, desc.timestampWrites.querySet, "querySet"),
+        desc: {
+          ...desc.label === void 0 ? {} : { label: desc.label },
+          timestampWrites: recordTimestampWrites(desc.timestampWrites)
+        }
       });
       realEnc.encodeEmptyComputePass(desc);
       pushEvent(s, { kind: "endComputePass", passHandleId: passHId });
@@ -7147,6 +7164,12 @@ function createCommandEncoderProxy(s, realEnc, cmdHId) {
     }
   };
 }
+function recordTimestampWrites(writes) {
+  return writes === void 0 ? void 0 : {
+    ...writes.beginningOfPassWriteIndex === void 0 ? {} : { beginningOfPassWriteIndex: writes.beginningOfPassWriteIndex },
+    ...writes.endOfPassWriteIndex === void 0 ? {} : { endOfPassWriteIndex: writes.endOfPassWriteIndex }
+  };
+}
 
 // src/recorder/pipeline.ts
 function wrapPipeline(state, pipeline, pipelineHandleId) {
@@ -9406,8 +9429,11 @@ function beginRenderPass(context, event, eventIndex) {
   if (event.occlusionQuerySetHandleId !== void 0 && 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 === void 0 ? {} : { timestampWrites: timestamp.value },
     colorAttachments: colors,
     ...depth?.kind === "texture-view" ? {
       depthStencilAttachment: {
@@ -9424,6 +9450,24 @@ function beginRenderPass(context, event, eventIndex) {
     eventRecord(event)
   );
 }
+function replayTimestampWrites(context, event, eventIndex) {
+  if (event.desc?.timestampWrites === void 0) return ok(void 0);
+  const handle = event.timestampQuerySetHandleId;
+  if (handle === void 0)
+    return missingResource(eventIndex, event, "timestamp-query-set", "query-set");
+  const query = requireResource(
+    context,
+    handle,
+    "query-set",
+    eventIndex,
+    event.kind
+  );
+  if (!query.ok) return query;
+  return ok({
+    ...event.desc.timestampWrites,
+    querySet: query.value
+  });
+}
 function beginComputePass(context, event, eventIndex) {
   const encoder = requireResource(
     context,
@@ -9434,7 +9478,12 @@ function beginComputePass(context, event, eventIndex) {
     "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 === void 0 ? {} : { label: event.desc.label },
+    ...timestamp.value === void 0 ? {} : { timestampWrites: timestamp.value }
+  });
   return context.table.set(
     event.passHandleId,
     { kind: "encoder", role: "compute-pass", value: pass },
@@ -9661,6 +9710,13 @@ async function readTexture(device, entry, resourceId, subresource, createShaderM
   const format = stringField2(descriptor, "format");
   const dimension = stringField2(descriptor, "dimension") ?? "2d";
   if (format === void 0) 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(
@@ -10734,9 +10790,10 @@ async function readWorkAttachment(context, index, work) {
       })
     );
   }
-  const viewId = begin.colorAttachmentViewHandleIds.find(
+  const attachmentIndex = begin.colorAttachmentViewHandleIds.findIndex(
     (candidate) => candidate !== void 0
   );
+  const viewId = begin.colorAttachmentResolveTargetHandleIds?.[attachmentIndex] ?? begin.colorAttachmentViewHandleIds[attachmentIndex];
   if (viewId === void 0) {
     return err(
       createRhiDebugError("readback-unsupported", {