@forgeax/engine-rhi-debug 0.1.4 → 0.1.7

package/src/replay/readback.ts

@@ -32,6 +32,13 @@ export interface TextureReadbackSubresource {
 
 export type ReplayReadbackRequest = BufferReadbackRange | TextureReadbackSubresource;
 
+export interface ReplayReadbackProvenance {
+  readonly generation: number;
+  readonly resourceId: string;
+  readonly subresource: ReplayReadbackRequest | null;
+  readonly selectedWorkIndex?: number;
+}
+
 export interface ReplayReadbackResult {
   readonly resourceId: string;
   readonly kind: 'buffer' | 'texture';
@@ -39,8 +46,11 @@ export interface ReplayReadbackResult {
   readonly width?: number;
   readonly height?: number;
   readonly bytes: Uint8Array;
+  readonly provenance: ReplayReadbackProvenance;
 }
 
+type ReplayReadbackPayload = Omit<ReplayReadbackResult, 'provenance'>;
+
 export async function readReplayResource(
   device: RhiDevice,
   table: ResourceTable,
@@ -51,18 +61,74 @@ export async function readReplayResource(
   const entry = table.get(resourceId);
   if (entry === undefined)
     return readbackFailure(`resource ${resourceId} is not present in the current generation`);
+  let result: Result<ReplayReadbackPayload, RhiDebugError>;
   if (entry.resource.kind === 'texture-view') {
     const sourceId = stringField(entry.descriptor, 'sourceHandleId');
     const source = sourceId === undefined ? undefined : table.get(sourceId);
     if (source === undefined || source.resource.kind !== 'texture') {
       return readbackFailure(`texture view ${resourceId} has no readable source texture`);
     }
-    return readTexture(device, source, resourceId, subresource, createShaderModule);
+    const sourceSubresource = resolveTextureViewSubresource(entry, source, subresource);
+    if (!sourceSubresource.ok) return sourceSubresource;
+    result = await readTexture(
+      device,
+      source,
+      resourceId,
+      sourceSubresource.value,
+      createShaderModule,
+    );
+  } else if (entry.resource.kind === 'texture') {
+    result = await readTexture(device, entry, resourceId, subresource, createShaderModule);
+  } else if (entry.resource.kind === 'buffer') {
+    result = await readBuffer(device, entry, resourceId, subresource);
+  } else {
+    return readbackFailure(`resource ${resourceId} is not readable by the v7 core matrix`);
+  }
+  if (!result.ok) return result;
+  return ok({
+    ...result.value,
+    provenance: {
+      generation: table.generation,
+      resourceId,
+      subresource: subresource ?? null,
+    },
+  });
+}
+
+function resolveTextureViewSubresource(
+  view: ResourceTableEntry,
+  source: ResourceTableEntry,
+  requested: ReplayReadbackRequest | undefined,
+): Result<ReplayReadbackRequest | undefined, RhiDebugError> {
+  if (requested === undefined || isBufferRange(requested)) return ok(requested);
+  const sourceDescriptor = recordField(source.descriptor, 'desc');
+  const sourceSize = textureSize(sourceDescriptor?.size);
+  const sourceMipCount = numberField(sourceDescriptor, 'mipLevelCount') ?? 1;
+  const viewDescriptor = recordField(view.descriptor, 'desc');
+  const baseMipLevel = numberField(viewDescriptor, 'baseMipLevel') ?? 0;
+  const baseArrayLayer = numberField(viewDescriptor, 'baseArrayLayer') ?? 0;
+  const mipLevelCount =
+    numberField(viewDescriptor, 'mipLevelCount') ?? sourceMipCount - baseMipLevel;
+  const arrayLayerCount =
+    numberField(viewDescriptor, 'arrayLayerCount') ??
+    sourceSize.depthOrArrayLayers - baseArrayLayer;
+  const localMipLevel = requested.mipLevel ?? 0;
+  const localArrayLayer = requested.arrayLayer ?? 0;
+  if (
+    !validIndex(baseMipLevel, sourceMipCount + 1) ||
+    !validIndex(baseArrayLayer, sourceSize.depthOrArrayLayers + 1) ||
+    !validIndex(localMipLevel, mipLevelCount) ||
+    !validIndex(localArrayLayer, arrayLayerCount) ||
+    baseMipLevel + mipLevelCount > sourceMipCount ||
+    baseArrayLayer + arrayLayerCount > sourceSize.depthOrArrayLayers
+  ) {
+    return readbackFailure('texture view subresource is outside the recorded view extent');
   }
-  if (entry.resource.kind === 'texture')
-    return readTexture(device, entry, resourceId, subresource, createShaderModule);
-  if (entry.resource.kind === 'buffer') return readBuffer(device, entry, resourceId, subresource);
-  return readbackFailure(`resource ${resourceId} is not readable by the v7 core matrix`);
+  return ok({
+    ...requested,
+    mipLevel: baseMipLevel + localMipLevel,
+    arrayLayer: baseArrayLayer + localArrayLayer,
+  });
 }
 
 async function readBuffer(
@@ -70,7 +136,7 @@ async function readBuffer(
   entry: ResourceTableEntry,
   resourceId: string,
   subresource: ReplayReadbackRequest | undefined,
-): Promise<Result<ReplayReadbackResult, RhiDebugError>> {
+): Promise<Result<ReplayReadbackPayload, RhiDebugError>> {
   const size = numberField(recordField(entry.descriptor, 'desc'), 'size');
   if (size === undefined || !Number.isSafeInteger(size) || size < 0)
     return readbackFailure(`buffer ${resourceId} has no valid recorded size`);
@@ -97,7 +163,7 @@ async function readTexture(
   resourceId: string,
   subresource: ReplayReadbackRequest | undefined,
   createShaderModule: CreateShaderModuleFn,
-): Promise<Result<ReplayReadbackResult, RhiDebugError>> {
+): Promise<Result<ReplayReadbackPayload, RhiDebugError>> {
   const descriptor = recordField(entry.descriptor, 'desc');
   const format = stringField(descriptor, 'format');
   const dimension = stringField(descriptor, 'dimension') ?? '2d';
@@ -128,18 +194,15 @@ async function readTexture(
   const width = Math.max(1, Math.floor(size.width / 2 ** mipLevel));
   const height = Math.max(1, Math.floor(size.height / 2 ** mipLevel));
   const requestedAspect = textureAspect(subresource);
-  if (format === 'depth24plus' || format === 'depth24plus-stencil8') {
-    if (format === 'depth24plus-stencil8' && requestedAspect === 'all') {
+  if (isDepthStencilTextureFormat(format)) {
+    if (requestedAspect === 'all') {
       return readbackUnsupported(
         resourceId,
         format,
-        'depth24plus-stencil8 requires an explicit depth-only or stencil-only aspect',
+        `${format} requires an explicit depth-only or stencil-only aspect`,
       );
     }
     if (requestedAspect === 'stencil-only') {
-      if (format !== 'depth24plus-stencil8') {
-        return readbackUnsupported(resourceId, format, 'depth24plus has no stencil aspect');
-      }
       const bytes = await copyTextureBytes(
         device,
         entry.resource.value as Texture,
@@ -157,6 +220,24 @@ async function readTexture(
       if (!bytes.ok) return bytes;
       return ok({ resourceId, kind: 'texture', format, width, height, bytes: bytes.value });
     }
+    if (format === 'depth24plus-stencil8') {
+      return blitDepth24PlusTexture(
+        device,
+        entry.resource.value as Texture,
+        resourceId,
+        format,
+        width,
+        height,
+        mipLevel,
+        arrayLayer,
+        createShaderModule,
+      );
+    }
+  }
+  if (format === 'depth24plus') {
+    if (requestedAspect === 'stencil-only') {
+      return readbackUnsupported(resourceId, format, 'depth24plus has no stencil aspect');
+    }
     return blitDepth24PlusTexture(
       device,
       entry.resource.value as Texture,
@@ -254,7 +335,7 @@ async function blitDepth24PlusTexture(
   mipLevel: number,
   arrayLayer: number,
   createShaderModule: CreateShaderModuleFn,
-): Promise<Result<ReplayReadbackResult, RhiDebugError>> {
+): Promise<Result<ReplayReadbackPayload, RhiDebugError>> {
   let output: Texture | undefined;
   let staging: Buffer | undefined;
   let mapped: MappedBuffer | undefined;
@@ -395,7 +476,10 @@ async function copyBufferBytes(
   let staging: Buffer | undefined;
   let mapped: MappedBuffer | undefined;
   try {
-    const created = device.createBuffer({ size: Math.max(4, size), usage: COPY_DST_MAP_READ });
+    const alignedSourceOffset = sourceOffset - (sourceOffset % 4);
+    const leadingBytes = sourceOffset - alignedSourceOffset;
+    const copySize = align4(leadingBytes + size);
+    const created = device.createBuffer({ size: Math.max(4, copySize), usage: COPY_DST_MAP_READ });
     if (!created.ok)
       return readbackFailure(`staging buffer creation failed: ${created.error.code}`);
     staging = created.value;
@@ -403,7 +487,7 @@ async function copyBufferBytes(
     if (!encoderResult.ok)
       return readbackFailure(`readback encoder creation failed: ${encoderResult.error.code}`);
     const encoder = encoderResult.value;
-    encoder.copyBufferToBuffer(source, sourceOffset, staging, 0, size);
+    encoder.copyBufferToBuffer(source, alignedSourceOffset, staging, 0, copySize);
     const finished = encoder.finish();
     if (!finished.ok)
       return readbackFailure(`readback encoder finish failed: ${finished.error.code}`);
@@ -413,9 +497,9 @@ async function copyBufferBytes(
     const mappedResult = await staging.mapAsync(GPU_MAP_MODE_READ);
     if (!mappedResult.ok) return readbackFailure(`readback map failed: ${mappedResult.error.code}`);
     mapped = mappedResult.value;
-    const range = mapped.getMappedRange(0, size);
+    const range = mapped.getMappedRange(0, copySize);
     if (!range.ok) return readbackFailure(`readback mapped range failed: ${range.error.code}`);
-    return ok(new Uint8Array(range.value).slice());
+    return ok(new Uint8Array(range.value).slice(leadingBytes, leadingBytes + size));
   } catch (cause) {
     return readbackFailure(`buffer readback failed: ${messageOf(cause)}`);
   } finally {
@@ -578,6 +662,10 @@ function align256(value: number): number {
   return Math.max(256, Math.ceil(value / 256) * 256);
 }
 
+function align4(value: number): number {
+  return Math.ceil(value / 4) * 4;
+}
+
 function messageOf(cause: unknown): string {
   return cause instanceof Error ? cause.message : String(cause);
 }

package/src/replay/session.ts

@@ -6,6 +6,7 @@ import type {
 } from '@forgeax/engine-rhi';
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { createRhiDebugError, type RhiDebugError } from '../errors';
+import { buildFrameModel, type WorkBinding, type WorkPipeline } from '../frame-model';
 import { buildTapeIndex, type TapeIndex, type TapeWorkEntry } from '../protocol/tape-index';
 import type { BootstrapResource, RhiCallEvent, Tape } from '../protocol/types';
 import type { CreateShaderModuleFn } from '../recorder';
@@ -38,6 +39,22 @@ export interface WorkInspection {
   readonly eventIndex: number;
   readonly passIndex: number;
   readonly attachment: ReplayReadbackResult | undefined;
+  readonly pipeline?: WorkPipeline;
+  readonly bindings?: readonly WorkBinding[];
+  readonly vertexBuffers?: readonly {
+    readonly slot: number;
+    readonly bufferHandleId: string;
+    readonly offset: number;
+    readonly size: number | null;
+  }[];
+  readonly indexBuffer?: {
+    readonly bufferHandleId: string;
+    readonly format: string;
+    readonly offset: number;
+    readonly size: number | null;
+  } | null;
+  readonly shaders?: WorkPipeline['shaders'];
+  readonly resourceIds?: readonly string[];
 }
 
 export interface ReplaySession {
@@ -71,6 +88,7 @@ export async function openReplay(
   if (capabilityFailure !== undefined) return err(capabilityFailure);
 
   const index = buildTapeIndex(tape);
+  const model = buildFrameModel(tape);
   const table = new ResourceTable(backend.device, 0);
   let disposed = false;
   let prepared = false;
@@ -112,7 +130,9 @@ export async function openReplay(
       if (disposed) return positionError(workIndex, index.works.length);
       if (signal?.aborted) return positionError(workIndex, index.works.length);
       const work = index.works[workIndex];
+      const modelWork = model.works[workIndex];
       if (work === undefined) return positionError(workIndex, index.works.length);
+      if (modelWork === undefined) return positionError(workIndex, index.works.length);
       const cleared = await reset();
       if (!cleared.ok) return cleared;
       const bootstrapped = await prepare();
@@ -123,11 +143,36 @@ export async function openReplay(
         ? await readWorkAttachment(context, index, work)
         : undefined;
       if (attachment !== undefined && !attachment.ok) return attachment;
-      return ok({
+      const selectedAttachment =
+        attachment?.ok === true
+          ? {
+              ...attachment.value,
+              provenance: {
+                ...attachment.value.provenance,
+                selectedWorkIndex: work.workIndex,
+              },
+            }
+          : undefined;
+      const baseInspection = {
         workIndex: work.workIndex,
         eventIndex: work.eventIndex,
         passIndex: work.passIndex,
-        attachment: attachment === undefined ? undefined : attachment.value,
+        attachment: selectedAttachment,
+      };
+      return ok({
+        ...baseInspection,
+        ...(fields?.includes('pipeline') ? { pipeline: modelWork.pipeline } : {}),
+        ...(fields?.includes('bindings')
+          ? {
+              bindings: modelWork.bindings,
+              vertexBuffers: modelWork.vertexBuffers,
+              indexBuffer: modelWork.indexBuffer,
+              shaders: modelWork.pipeline.shaders,
+              resourceIds: modelWork.bindings
+                .map((binding) => binding.resourceId)
+                .filter((resourceId): resourceId is string => resourceId !== null),
+            }
+          : {}),
       });
     },
     async readResource(resourceId, subresource, signal) {

package/src/texel-decode.ts

@@ -146,21 +146,26 @@ function readTexel(
 }
 
 /**
- * Decode tight raw GPU bytes of an uncompressed color texture into RGBA8 the
- * canvas can paint via putImageData. Returns null when the format has no
- * {@link formatInfo} entry (compressed / depth / unknown -> caller falls back).
+ * Decode tight raw GPU bytes of a supported color or depth/stencil plane into
+ * RGBA8 the canvas can paint via putImageData. Returns null when the format has
+ * no {@link formatInfo} entry or the requested aspect is invalid.
  *
  * @param bytes - Tight readback bytes (no row padding), length = w*h*bytesPerTexel.
  * @param format - The texture's real format string.
  * @param width - Texture width in pixels.
  * @param height - Texture height in pixels.
+ * @param aspect - Explicit plane selected by readback for depth/stencil formats.
  */
 export function decodeToRgba8(
   bytes: Uint8Array,
   format: string,
   width: number,
   height: number,
+  aspect: 'all' | 'depth-only' | 'stencil-only' = 'all',
 ): Uint8ClampedArray<ArrayBuffer> | null {
+  if (format.startsWith('depth')) {
+    return decodeDepthToRgba8(bytes, format, width, height, aspect);
+  }
   const info = formatInfo(format);
   const texBytes = bytesPerTexel(format as never);
   if (!info || texBytes === undefined) return null;
@@ -198,6 +203,35 @@ export function decodeToRgba8(
   return out;
 }
 
+function decodeDepthToRgba8(
+  bytes: Uint8Array,
+  format: string,
+  width: number,
+  height: number,
+  aspect: 'all' | 'depth-only' | 'stencil-only',
+): Uint8ClampedArray<ArrayBuffer> | null {
+  const combined = format.endsWith('-stencil8');
+  if (combined && aspect === 'all') return null;
+  if (!combined && aspect === 'stencil-only') return null;
+  const stencil = aspect === 'stencil-only';
+  const bytesPerValue = stencil ? 1 : 4;
+  const texelCount = width * height;
+  if (bytes.byteLength < texelCount * bytesPerValue) return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const out = new Uint8ClampedArray(new ArrayBuffer(texelCount * 4));
+  for (let index = 0; index < texelCount; index++) {
+    const value = stencil
+      ? view.getUint8(index)
+      : Math.round(clamp01(view.getFloat32(index * 4, true)) * 255);
+    const target = index * 4;
+    out[target] = value;
+    out[target + 1] = value;
+    out[target + 2] = value;
+    out[target + 3] = 255;
+  }
+  return out;
+}
+
 /**
  * Decode a single texel from tight raw GPU bytes into raw float RGBA values
  * without the display clamp (D-4: raw byte bypass for HDR fidelity).

package/src/types.ts

@@ -169,11 +169,21 @@ export interface RhiCallEventCreateRenderPipeline {
   readonly kind: 'createRenderPipeline';
   readonly handleId: HandleId;
   readonly desc: {
-    readonly vertex?: GPUVertexState | undefined;
+    /** Serialized stage omits opaque shader module; the handle id is authoritative. */
+    readonly vertex?: {
+      readonly entryPoint?: string | undefined;
+      readonly buffers: Iterable<GPUVertexBufferLayout | null | undefined>;
+      readonly constants?: Record<string, number> | undefined;
+    };
     readonly primitive?: GPUPrimitiveState | undefined;
     readonly depthStencil?: GPUDepthStencilState | undefined;
     readonly multisample?: GPUMultisampleState | undefined;
-    readonly fragment?: GPUFragmentState | undefined;
+    /** Serialized stage omits opaque shader module; the handle id is authoritative. */
+    readonly fragment?: {
+      readonly entryPoint?: string | undefined;
+      readonly targets: Iterable<GPUColorTargetState | null | undefined>;
+      readonly constants?: Record<string, number> | undefined;
+    };
   };
   readonly layoutHandleId: HandleId;
   /** HandleId of the re-created vertex shader module for cross-device binding. */
@@ -261,10 +271,24 @@ export interface RhiCallEventBeginRenderPass {
   readonly cmdHandleId: HandleId;
   readonly passHandleId: HandleId;
   readonly desc: {
-    readonly colorAttachments: Iterable<GPURenderPassColorAttachment | null | undefined>;
-    readonly depthStencilAttachment?: GPURenderPassDepthStencilAttachment | undefined;
-    readonly occlusionQuerySet?: GPUQuerySet | undefined;
-    readonly timestampWrites?: GPURenderPassTimestampWrites | undefined;
+    /** Attachment handles are replaced by the parallel HandleId arrays on replay. */
+    readonly colorAttachments: Iterable<
+      | {
+          readonly view: unknown;
+          readonly resolveTarget?: unknown;
+          readonly [key: string]: unknown;
+        }
+      | null
+      | undefined
+    >;
+    readonly depthStencilAttachment?:
+      | {
+          readonly view: unknown;
+          readonly [key: string]: unknown;
+        }
+      | undefined;
+    readonly occlusionQuerySet?: unknown | undefined;
+    readonly timestampWrites?: unknown | undefined;
     readonly maxDrawCount?: number | undefined;
   };
   readonly colorAttachmentViewHandleIds: readonly (HandleId | undefined)[];