@forgeax/engine-rhi-debug 0.1.2

package/src/texel-decode.ts

@@ -0,0 +1,255 @@
+// texel-decode.ts -- CPU decode of each uncompressed color format to RGBA8 for preview.
+//
+// The recorder promotes COPY_SRC onto every createTexture, so the replayer's
+// copyTextureToBuffer reads back each uncompressed color texture's raw bytes
+// faithfully (no format change -- replay fidelity intact). This module turns
+// those raw bytes into displayable RGBA8 entirely on the host:
+//
+//   raw bytes --formatInfo--> per-channel values --[display map]--> RGBA8
+//
+// Display map (RenderDoc's default initial state, confirmed with the user):
+//   float/ufloat -> clamp(v, 0, 1) * 255     (HDR highlights >1 saturate to white)
+//   unorm        -> v * 255                   (already 0..1)
+//   snorm        -> clamp(v, 0, 1) * 255      (negatives clip to black)
+//   uint/sint    -> clamp(v, 0, 255)          (small integer ids stay visible)
+//
+// Channels -> RGBA: 1ch grayscale (R=G=B), 2ch (R,G,B=0), 3ch (RGB,A=255), 4ch.
+//
+// Related: plan "all-format color preview"; reuses formatInfo (rhi-debug texel-layout).
+
+import { bytesPerTexel, type FormatInfo, formatInfo } from './texel-layout';
+
+/** Decode a single IEEE half-float (16-bit) bit pattern to a JS number. */
+export function halfToFloat(h: number): number {
+  const sign = (h & 0x8000) >> 15;
+  const exp = (h & 0x7c00) >> 10;
+  const frac = h & 0x03ff;
+  const s = sign === 0 ? 1 : -1;
+  if (exp === 0) {
+    // Subnormal (or zero): 2^-14 * (frac / 1024).
+    return s * 2 ** -14 * (frac / 1024);
+  }
+  if (exp === 0x1f) {
+    // Inf / NaN.
+    return frac === 0 ? s * Number.POSITIVE_INFINITY : Number.NaN;
+  }
+  // Normal: 2^(exp-15) * (1 + frac/1024).
+  return s * 2 ** (exp - 15) * (1 + frac / 1024);
+}
+
+/**
+ * Decode an unsigned-int bit pattern of an 11- or 10-bit unsigned float
+ * (rg11b10ufloat layout: no sign bit). 11-bit = 5 exp + 6 mantissa; 10-bit =
+ * 5 exp + 5 mantissa. Bias 15, matching the f16 exponent.
+ */
+function smallUFloatToFloat(bits: number, mantissaBits: number): number {
+  const expBits = 5;
+  const exp = (bits >> mantissaBits) & ((1 << expBits) - 1);
+  const mantMax = 1 << mantissaBits;
+  const frac = bits & (mantMax - 1);
+  if (exp === 0) return 2 ** -14 * (frac / mantMax);
+  if (exp === 0x1f) return frac === 0 ? Number.POSITIVE_INFINITY : Number.NaN;
+  return 2 ** (exp - 15) * (1 + frac / mantMax);
+}
+
+const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
+
+/** Map one decoded channel value to a 0..255 display byte by channel type. */
+function toByte(v: number, channelType: FormatInfo['channelType']): number {
+  // uint/sint: small integer ids stay visible (clamp 0..255, no normalize).
+  if (channelType === 'uint' || channelType === 'sint') {
+    return Math.round(v < 0 ? 0 : v > 255 ? 255 : v);
+  }
+  // float/ufloat clamp HDR to [0,1]; unorm already 0..1; snorm clips negatives.
+  return Math.round(clamp01(v) * 255);
+}
+
+/**
+ * Read the `channels` raw channel values of one texel at byte offset `off`.
+ * Plain formats read each channel at a uniform per-channel byte width; packed
+ * formats unpack the single 32-bit word by bit-field. Values are returned in the
+ * format's native channel order (BGRA swizzle handled by the caller).
+ */
+function readTexel(
+  view: DataView,
+  off: number,
+  info: FormatInfo,
+  channelBytes: number,
+): [number, number, number, number] {
+  const out: [number, number, number, number] = [0, 0, 0, 1];
+
+  if (info.packed === 'rgb10a2unorm') {
+    const word = view.getUint32(off, true);
+    out[0] = (word & 0x3ff) / 1023;
+    out[1] = ((word >> 10) & 0x3ff) / 1023;
+    out[2] = ((word >> 20) & 0x3ff) / 1023;
+    out[3] = ((word >> 30) & 0x3) / 3;
+    return out;
+  }
+  if (info.packed === 'rg11b10ufloat') {
+    const word = view.getUint32(off, true);
+    out[0] = smallUFloatToFloat(word & 0x7ff, 6);
+    out[1] = smallUFloatToFloat((word >> 11) & 0x7ff, 6);
+    out[2] = smallUFloatToFloat((word >> 22) & 0x3ff, 5);
+    out[3] = 1;
+    return out;
+  }
+
+  for (let c = 0; c < info.channels; c++) {
+    const co = off + c * channelBytes;
+    let v: number;
+    switch (info.channelType) {
+      case 'float':
+        v = channelBytes === 2 ? halfToFloat(view.getUint16(co, true)) : view.getFloat32(co, true);
+        break;
+      case 'unorm':
+        v =
+          channelBytes === 1
+            ? view.getUint8(co) / 255
+            : channelBytes === 2
+              ? view.getUint16(co, true) / 65535
+              : view.getUint32(co, true) / 4294967295;
+        break;
+      case 'snorm': {
+        const raw =
+          channelBytes === 1
+            ? view.getInt8(co)
+            : channelBytes === 2
+              ? view.getInt16(co, true)
+              : view.getInt32(co, true);
+        const denom = channelBytes === 1 ? 127 : channelBytes === 2 ? 32767 : 2147483647;
+        v = Math.max(-1, raw / denom);
+        break;
+      }
+      case 'uint':
+        v =
+          channelBytes === 1
+            ? view.getUint8(co)
+            : channelBytes === 2
+              ? view.getUint16(co, true)
+              : view.getUint32(co, true);
+        break;
+      case 'sint':
+        v =
+          channelBytes === 1
+            ? view.getInt8(co)
+            : channelBytes === 2
+              ? view.getInt16(co, true)
+              : view.getInt32(co, true);
+        break;
+      default:
+        v = 0;
+    }
+    out[c] = v;
+  }
+  return out;
+}
+
+/**
+ * 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).
+ *
+ * @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.
+ */
+export function decodeToRgba8(
+  bytes: Uint8Array,
+  format: string,
+  width: number,
+  height: number,
+): Uint8ClampedArray<ArrayBuffer> | null {
+  const info = formatInfo(format);
+  const texBytes = bytesPerTexel(format as never);
+  if (!info || texBytes === undefined) return null;
+
+  // Per-channel byte width for plain formats (packed formats ignore this).
+  const channelBytes = info.packed ? texBytes : texBytes / info.channels;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  // Explicit ArrayBuffer backing (not ArrayBufferLike) so ImageData accepts it.
+  const out = new Uint8ClampedArray(new ArrayBuffer(width * height * 4));
+
+  for (let i = 0; i < width * height; i++) {
+    const [c0, c1, c2, c3] = readTexel(view, i * texBytes, info, channelBytes);
+    const di = i * 4;
+    if (info.channels === 1) {
+      const g = toByte(c0, info.channelType);
+      out[di] = g;
+      out[di + 1] = g;
+      out[di + 2] = g;
+      out[di + 3] = 255;
+    } else if (info.channels === 2) {
+      out[di] = toByte(c0, info.channelType);
+      out[di + 1] = toByte(c1, info.channelType);
+      out[di + 2] = 0;
+      out[di + 3] = 255;
+    } else {
+      // 3 or 4 channels. BGRA stores blue-first -> swizzle B<->R.
+      const r = info.bgra ? c2 : c0;
+      const b = info.bgra ? c0 : c2;
+      out[di] = toByte(r, info.channelType);
+      out[di + 1] = toByte(c1, info.channelType);
+      out[di + 2] = toByte(b, info.channelType);
+      out[di + 3] = info.channels === 4 ? toByte(c3, info.channelType) : 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).
+ *
+ * Unlike `decodeToRgba8` which clamps float/ufloat to [0,1] for display, this
+ * returns the decoded per-channel values as-is: float formats keep true values
+ * (2.5 stays 2.5, negative stays negative), unorm/snorm stay in their native
+ * ranges, uint/sint stay as integers cast to number.
+ *
+ * Channels: 1ch grayscale (R=G=B, A=1), 2ch (RG, B=0, A=1), 3/4ch (RGBA or
+ * BGRA→swizzled). Returns null when the format has no {@link formatInfo} entry.
+ *
+ * @param bytes - Tight readback bytes, length = width*height*bytesPerTexel.
+ * @param format - The texture's real format string.
+ * @param width - Texture width in pixels.
+ * @param height - Texture height in pixels.
+ * @param texelX - 0-based column of the target texel.
+ * @param texelY - 0-based row of the target texel.
+ */
+export function decodeTexelRaw(
+  bytes: Uint8Array,
+  format: string,
+  width: number,
+  height: number,
+  texelX: number,
+  texelY: number,
+): [number, number, number, number] | null {
+  if (texelX < 0 || texelX >= width || texelY < 0 || texelY >= height) return null;
+
+  const info = formatInfo(format);
+  const texBytes = bytesPerTexel(format as never);
+  if (!info || texBytes === undefined) return null;
+
+  const texelIdx = texelY * width + texelX;
+  const byteOffset = texelIdx * texBytes;
+
+  // Guard: the buffer must be large enough for this texel.
+  if (byteOffset + texBytes > bytes.byteLength) return null;
+
+  const channelBytes = info.packed ? texBytes : texBytes / info.channels;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const channels = readTexel(view, byteOffset, info, channelBytes);
+
+  if (info.channels === 1) {
+    return [channels[0], channels[0], channels[0], 1];
+  }
+  if (info.channels === 2) {
+    return [channels[0], channels[1], 0, 1];
+  }
+  // 3 or 4 channels. BGRA swizzle B<->R.
+  const r = info.bgra ? channels[2] : channels[0];
+  const b = info.bgra ? channels[0] : channels[2];
+  const a = info.channels === 4 ? channels[3] : 1;
+  return [r, channels[1], b, a];
+}

package/src/texel-layout.ts

@@ -0,0 +1,324 @@
+/// <reference types="@webgpu/types" />
+// @forgeax/engine-rhi-debug/texel-layout -- SSOT for how a color texture's GPU
+// bytes are laid out, shared by the snapshot readback (recorder) and the seed
+// write-back (replayer) so both agree on byte layout without duplicating it in
+// the tape (architecture-principles #1 SSOT / #2 Derive: format + size +
+// mipLevelCount already live in the createTexture event; layout is derived, not
+// re-stored in the initialData event).
+//
+// Why this exists: the original frame-header snapshot hardcoded bytesPerRow =
+// width*4, depthOrArrayLayers = 1, mipLevel = 0 -- correct only for a single-mip
+// single-layer 4-byte texture (rgba8). IBL resources break all three: the
+// irradiance/prefilter cubemaps are rgba16float (8 B/texel), 6 array layers, and
+// the prefilter map has a 5-mip roughness chain. Snapshotting them with the old
+// assumptions either skipped them (-> replay renders unlit/black) or would have
+// seeded corrupt bytes. This module computes the real per-subresource layout so a
+// full snapshot + faithful seed round-trips each color format with a known texel
+// block footprint, including block-compressed formats.
+
+/**
+ * Bytes per texel for uncompressed color formats. Block-compressed formats use
+ * {@link textureBlockLayout} because their bytes are addressed by blocks.
+ */
+export function bytesPerTexel(format: GPUTextureFormat | undefined): number | undefined {
+  if (format === undefined) return undefined;
+  return TEXEL_BYTES[format];
+}
+
+// Uncompressed color formats only. Keyed to the W3C WebGPU GPUTextureFormat
+// names. Depth/stencil and block-compressed formats are deliberately absent.
+const TEXEL_BYTES: Partial<Record<GPUTextureFormat, number>> = {
+  // 8-bit channels
+  r8unorm: 1,
+  r8snorm: 1,
+  r8uint: 1,
+  r8sint: 1,
+  rg8unorm: 2,
+  rg8snorm: 2,
+  rg8uint: 2,
+  rg8sint: 2,
+  rgba8unorm: 4,
+  'rgba8unorm-srgb': 4,
+  rgba8snorm: 4,
+  rgba8uint: 4,
+  rgba8sint: 4,
+  bgra8unorm: 4,
+  'bgra8unorm-srgb': 4,
+  // 16-bit channels
+  r16uint: 2,
+  r16sint: 2,
+  r16float: 2,
+  rg16uint: 4,
+  rg16sint: 4,
+  rg16float: 4,
+  rgba16uint: 8,
+  rgba16sint: 8,
+  rgba16float: 8,
+  // 32-bit channels
+  r32uint: 4,
+  r32sint: 4,
+  r32float: 4,
+  rg32uint: 8,
+  rg32sint: 8,
+  rg32float: 8,
+  rgba32uint: 16,
+  rgba32sint: 16,
+  rgba32float: 16,
+  // packed
+  rgb10a2unorm: 4,
+  rg11b10ufloat: 4,
+};
+
+export interface TextureBlockLayout {
+  readonly blockWidth: number;
+  readonly blockHeight: number;
+  readonly bytesPerBlock: number;
+}
+
+const COMPRESSED_BLOCKS: Partial<Record<GPUTextureFormat, TextureBlockLayout>> = {
+  // BCn: all formats use 4x4 blocks; BC1/BC4 are 8 bytes, the rest 16.
+  'bc1-rgba-unorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 8 },
+  'bc1-rgba-unorm-srgb': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 8 },
+  'bc2-rgba-unorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'bc2-rgba-unorm-srgb': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'bc3-rgba-unorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'bc3-rgba-unorm-srgb': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'bc4-r-unorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 8 },
+  'bc4-r-snorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 8 },
+  'bc5-rg-unorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'bc5-rg-snorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'bc6h-rgb-ufloat': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'bc6h-rgb-float': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'bc7-rgba-unorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'bc7-rgba-unorm-srgb': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  // ETC2/EAC: all formats use 4x4 blocks; one or two 64-bit blocks.
+  'etc2-rgb8unorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 8 },
+  'etc2-rgb8unorm-srgb': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 8 },
+  'etc2-rgb8a1unorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 8 },
+  'etc2-rgb8a1unorm-srgb': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 8 },
+  'etc2-rgba8unorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'etc2-rgba8unorm-srgb': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'eac-r11unorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 8 },
+  'eac-r11snorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 8 },
+  'eac-rg11unorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'eac-rg11snorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  // ASTC uses 16-byte blocks with a format-specific footprint.
+  'astc-4x4-unorm': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'astc-4x4-unorm-srgb': { blockWidth: 4, blockHeight: 4, bytesPerBlock: 16 },
+  'astc-5x4-unorm': { blockWidth: 5, blockHeight: 4, bytesPerBlock: 16 },
+  'astc-5x4-unorm-srgb': { blockWidth: 5, blockHeight: 4, bytesPerBlock: 16 },
+  'astc-5x5-unorm': { blockWidth: 5, blockHeight: 5, bytesPerBlock: 16 },
+  'astc-5x5-unorm-srgb': { blockWidth: 5, blockHeight: 5, bytesPerBlock: 16 },
+  'astc-6x5-unorm': { blockWidth: 6, blockHeight: 5, bytesPerBlock: 16 },
+  'astc-6x5-unorm-srgb': { blockWidth: 6, blockHeight: 5, bytesPerBlock: 16 },
+  'astc-6x6-unorm': { blockWidth: 6, blockHeight: 6, bytesPerBlock: 16 },
+  'astc-6x6-unorm-srgb': { blockWidth: 6, blockHeight: 6, bytesPerBlock: 16 },
+  'astc-8x5-unorm': { blockWidth: 8, blockHeight: 5, bytesPerBlock: 16 },
+  'astc-8x5-unorm-srgb': { blockWidth: 8, blockHeight: 5, bytesPerBlock: 16 },
+  'astc-8x6-unorm': { blockWidth: 8, blockHeight: 6, bytesPerBlock: 16 },
+  'astc-8x6-unorm-srgb': { blockWidth: 8, blockHeight: 6, bytesPerBlock: 16 },
+  'astc-8x8-unorm': { blockWidth: 8, blockHeight: 8, bytesPerBlock: 16 },
+  'astc-8x8-unorm-srgb': { blockWidth: 8, blockHeight: 8, bytesPerBlock: 16 },
+  'astc-10x5-unorm': { blockWidth: 10, blockHeight: 5, bytesPerBlock: 16 },
+  'astc-10x5-unorm-srgb': { blockWidth: 10, blockHeight: 5, bytesPerBlock: 16 },
+  'astc-10x6-unorm': { blockWidth: 10, blockHeight: 6, bytesPerBlock: 16 },
+  'astc-10x6-unorm-srgb': { blockWidth: 10, blockHeight: 6, bytesPerBlock: 16 },
+  'astc-10x8-unorm': { blockWidth: 10, blockHeight: 8, bytesPerBlock: 16 },
+  'astc-10x8-unorm-srgb': { blockWidth: 10, blockHeight: 8, bytesPerBlock: 16 },
+  'astc-10x10-unorm': { blockWidth: 10, blockHeight: 10, bytesPerBlock: 16 },
+  'astc-10x10-unorm-srgb': { blockWidth: 10, blockHeight: 10, bytesPerBlock: 16 },
+  'astc-12x10-unorm': { blockWidth: 12, blockHeight: 10, bytesPerBlock: 16 },
+  'astc-12x10-unorm-srgb': { blockWidth: 12, blockHeight: 10, bytesPerBlock: 16 },
+  'astc-12x12-unorm': { blockWidth: 12, blockHeight: 12, bytesPerBlock: 16 },
+  'astc-12x12-unorm-srgb': { blockWidth: 12, blockHeight: 12, bytesPerBlock: 16 },
+};
+
+/** Return the WebGPU texel-block footprint for each supported color format. */
+export function textureBlockLayout(
+  format: GPUTextureFormat | undefined,
+): TextureBlockLayout | undefined {
+  if (format === undefined) return undefined;
+  return (
+    COMPRESSED_BLOCKS[format] ??
+    (TEXEL_BYTES[format] === undefined
+      ? undefined
+      : { blockWidth: 1, blockHeight: 1, bytesPerBlock: TEXEL_BYTES[format] })
+  );
+}
+
+// ============================================================================
+// formatInfo -- per-channel semantics for CPU-side decode (viewer preview)
+// ============================================================================
+
+/** How a channel's bits are interpreted (drives the host-side decode-to-RGBA8). */
+export type ChannelType = 'unorm' | 'snorm' | 'uint' | 'sint' | 'float' | 'ufloat';
+
+/**
+ * Per-channel layout of an uncompressed color format, enough to decode its raw
+ * GPU bytes into displayable RGBA8 on the host (no GPU). Sits beside
+ * {@link bytesPerTexel} (which stays the SSOT for total texel size); the
+ * per-channel byte width is derived as `bytesPerTexel / channels` for plain
+ * formats, so no byte count is re-stored here. `packed` formats pack all
+ * channels into a single 4-byte word (channels read by bit-field, not by a
+ * uniform per-channel width).
+ */
+export interface FormatInfo {
+  readonly channels: 1 | 2 | 3 | 4;
+  readonly channelType: ChannelType;
+  /** Channels stored blue-first in memory (swizzle B<->R when decoding). */
+  readonly bgra?: boolean;
+  /** Bit-packed layout (channels share one 32-bit word) needing special unpack. */
+  readonly packed?: 'rgb10a2unorm' | 'rg11b10ufloat';
+}
+
+// Keyed to the same uncompressed color formats as TEXEL_BYTES. Depth/stencil and
+// block-compressed formats are absent (return undefined -> caller falls back).
+const FORMAT_INFO: Partial<Record<GPUTextureFormat, FormatInfo>> = {
+  // 8-bit channels
+  r8unorm: { channels: 1, channelType: 'unorm' },
+  r8snorm: { channels: 1, channelType: 'snorm' },
+  r8uint: { channels: 1, channelType: 'uint' },
+  r8sint: { channels: 1, channelType: 'sint' },
+  rg8unorm: { channels: 2, channelType: 'unorm' },
+  rg8snorm: { channels: 2, channelType: 'snorm' },
+  rg8uint: { channels: 2, channelType: 'uint' },
+  rg8sint: { channels: 2, channelType: 'sint' },
+  rgba8unorm: { channels: 4, channelType: 'unorm' },
+  'rgba8unorm-srgb': { channels: 4, channelType: 'unorm' },
+  rgba8snorm: { channels: 4, channelType: 'snorm' },
+  rgba8uint: { channels: 4, channelType: 'uint' },
+  rgba8sint: { channels: 4, channelType: 'sint' },
+  bgra8unorm: { channels: 4, channelType: 'unorm', bgra: true },
+  'bgra8unorm-srgb': { channels: 4, channelType: 'unorm', bgra: true },
+  // 16-bit channels
+  r16uint: { channels: 1, channelType: 'uint' },
+  r16sint: { channels: 1, channelType: 'sint' },
+  r16float: { channels: 1, channelType: 'float' },
+  rg16uint: { channels: 2, channelType: 'uint' },
+  rg16sint: { channels: 2, channelType: 'sint' },
+  rg16float: { channels: 2, channelType: 'float' },
+  rgba16uint: { channels: 4, channelType: 'uint' },
+  rgba16sint: { channels: 4, channelType: 'sint' },
+  rgba16float: { channels: 4, channelType: 'float' },
+  // 32-bit channels
+  r32uint: { channels: 1, channelType: 'uint' },
+  r32sint: { channels: 1, channelType: 'sint' },
+  r32float: { channels: 1, channelType: 'float' },
+  rg32uint: { channels: 2, channelType: 'uint' },
+  rg32sint: { channels: 2, channelType: 'sint' },
+  rg32float: { channels: 2, channelType: 'float' },
+  rgba32uint: { channels: 4, channelType: 'uint' },
+  rgba32sint: { channels: 4, channelType: 'sint' },
+  rgba32float: { channels: 4, channelType: 'float' },
+  // packed (channels share one 32-bit word; decoded by bit-field)
+  rgb10a2unorm: { channels: 4, channelType: 'unorm', packed: 'rgb10a2unorm' },
+  rg11b10ufloat: { channels: 3, channelType: 'ufloat', packed: 'rg11b10ufloat' },
+};
+
+/**
+ * Per-channel layout of an uncompressed color format for host-side decode.
+ * Returns `undefined` for depth/stencil, block-compressed, or unknown formats
+ * (the viewer's preview path treats `undefined` as "not directly previewable").
+ */
+export function formatInfo(format: GPUTextureFormat | string | undefined): FormatInfo | undefined {
+  if (format === undefined) return undefined;
+  return FORMAT_INFO[format as GPUTextureFormat];
+}
+
+/** One mip level of one array layer: its extent + where its tight bytes live in the blob. */
+export interface SubresourceSlice {
+  readonly layer: number;
+  readonly mip: number;
+  readonly width: number;
+  readonly height: number;
+  readonly byteOffset: number;
+  readonly byteLength: number;
+}
+
+/** Full subresource layout of a texture snapshot blob. */
+export interface TextureLayout {
+  readonly blockWidth: number;
+  readonly blockHeight: number;
+  readonly bytesPerBlock: number;
+  readonly layerCount: number;
+  readonly mipLevelCount: number;
+  readonly slices: readonly SubresourceSlice[];
+  /** Total tight byte length across every subresource (the blob size). */
+  readonly totalBytes: number;
+}
+
+export interface TextureExtent {
+  readonly width: number;
+  readonly height: number;
+  readonly layerCount: number;
+}
+
+/** Project a serialized GPU texture extent onto the dimensions used by snapshots. */
+export function projectTextureExtent(size: unknown): TextureExtent {
+  if (typeof size === 'number') return { width: size, height: 1, layerCount: 1 };
+  if (Array.isArray(size)) {
+    const width = typeof size[0] === 'number' ? size[0] : 1;
+    const height = typeof size[1] === 'number' ? size[1] : width;
+    const layerCount = typeof size[2] === 'number' ? size[2] : 1;
+    return { width, height, layerCount };
+  }
+  if (size !== null && typeof size === 'object') {
+    const record = size as {
+      readonly width?: unknown;
+      readonly height?: unknown;
+      readonly depthOrArrayLayers?: unknown;
+    };
+    const width = typeof record.width === 'number' ? record.width : 1;
+    const height = typeof record.height === 'number' ? record.height : width;
+    const layerCount =
+      typeof record.depthOrArrayLayers === 'number' ? record.depthOrArrayLayers : 1;
+    return { width, height, layerCount };
+  }
+  return { width: 1, height: 1, layerCount: 1 };
+}
+
+/**
+ * Compute the canonical tight byte layout for a texture snapshot: every array
+ * layer, every mip level, packed in layer-major then mip-minor order with no row
+ * padding (tight bytesPerRow = blockCountX * bytesPerBlock). Mip dimensions halve
+ * per level (floor, min 1), matching the WebGPU mip size rule.
+ *
+ * Returns `undefined` when the format has no known block footprint. The
+ * recorder reads each slice into this exact offset; the replayer reads each
+ * slice back out and writeTexture's it to (layer, mip).
+ */
+export function computeTextureLayout(
+  format: GPUTextureFormat | undefined,
+  width: number,
+  height: number,
+  layerCount: number,
+  mipLevelCount: number,
+): TextureLayout | undefined {
+  const block = textureBlockLayout(format);
+  if (block === undefined) return undefined;
+
+  const layers = Math.max(1, layerCount);
+  const mips = Math.max(1, mipLevelCount);
+  const slices: SubresourceSlice[] = [];
+  let offset = 0;
+  for (let layer = 0; layer < layers; layer++) {
+    for (let mip = 0; mip < mips; mip++) {
+      const mw = Math.max(1, width >> mip);
+      const mh = Math.max(1, height >> mip);
+      const blockCountX = Math.ceil(mw / block.blockWidth);
+      const blockCountY = Math.ceil(mh / block.blockHeight);
+      const byteLength = blockCountX * blockCountY * block.bytesPerBlock;
+      slices.push({ layer, mip, width: mw, height: mh, byteOffset: offset, byteLength });
+      offset += byteLength;
+    }
+  }
+  return {
+    blockWidth: block.blockWidth,
+    blockHeight: block.blockHeight,
+    bytesPerBlock: block.bytesPerBlock,
+    layerCount: layers,
+    mipLevelCount: mips,
+    slices,
+    totalBytes: offset,
+  };
+}