@plasius/gpu-renderer 0.2.40 → 0.2.42

package/dist/index.cjs

@@ -2441,6 +2441,8 @@ function createWavefrontTransportGuardrailSummary(frameStats, options = {}) {
     0,
     Number(frameStats?.radianceDiagnostics?.legacyClampEquivalentSamples ?? 0)
   );
+  const rayCountStatus = typeof frameStats?.rayCounts?.status === "string" ? frameStats.rayCounts.status : "not-requested";
+  const rayCountReason = typeof frameStats?.rayCounts?.reason === "string" ? frameStats.rayCounts.reason : null;
   const memory = summarizeWavefrontMemory(frameStats?.memory);
   const checks = Object.freeze([
     createTransportGuardrailCheck(
@@ -2462,6 +2464,11 @@ function createWavefrontTransportGuardrailSummary(frameStats, options = {}) {
       "radiance-diagnostics",
       invalidSamples > 0 ? "fail" : legacyClampEquivalentSamples > 0 ? "warn" : "pass",
       invalidSamples > 0 ? `Renderer recorded ${invalidSamples} invalid radiance sample(s); inspect transport math before trusting the frame.` : legacyClampEquivalentSamples > 0 ? `${legacyClampEquivalentSamples} weighted sample(s) exceeded the legacy 4.0 preview clamp threshold; convergence stayed unbiased, but review firefly diagnostics before rollout.` : "No invalid radiance samples or legacy-clamp-equivalent fireflies were recorded."
+    ),
+    createTransportGuardrailCheck(
+      "ray-count-telemetry",
+      rayCountStatus === "failed" ? "fail" : rayCountStatus === "unavailable" ? "warn" : "pass",
+      rayCountStatus === "failed" ? `Ray-count telemetry failed closed: ${rayCountReason ?? "unknown failure"}.` : rayCountStatus === "unavailable" ? `Ray-count telemetry was requested but unavailable: ${rayCountReason ?? "unknown reason"}.` : rayCountStatus === "available" ? "Primary, secondary, and total path-segment counts were captured." : "Ray-count telemetry was not requested for this frame."
     )
   ]);
   const status = checks.some((check) => check.status === "fail") ? "fail" : checks.some((check) => check.status === "warn") ? "warn" : "pass";
@@ -2482,6 +2489,7 @@ function createWavefrontTransportGuardrailSummary(frameStats, options = {}) {
         invalidSamples,
         legacyClampEquivalentSamples
       }),
+      rayCountStatus,
       memory
     }),
     checks
@@ -2592,6 +2600,7 @@ var COUNTER_TRANSPORT_RESIDUAL_LUMINANCE_OFFSET = 22;
 var COUNTER_TRANSPORT_ZERO_TERMINATION_OFFSET = 23;
 var COUNTER_TRANSPORT_CHECKSUM_OFFSET = 24;
 var TRACE_STORAGE_BUFFER_BINDINGS = 10;
+var TRACE_SAMPLED_TEXTURE_BINDINGS = 21;
 var BRDF_LUT_UPLOAD_CACHE = /* @__PURE__ */ new Map();
 var MATERIAL_DIFFUSE = 0;
 var MATERIAL_METAL = 1;
@@ -2650,6 +2659,7 @@ var EMPTY_TERMINATION_METRICS = Object.freeze({
 var wavefrontPathTracingComputeLimits = Object.freeze({
   workgroupSize: WORKGROUP_SIZE,
   traceStorageBufferBindings: TRACE_STORAGE_BUFFER_BINDINGS,
+  traceSampledTextureBindings: TRACE_SAMPLED_TEXTURE_BINDINGS,
   rayRecordBytes: RAY_RECORD_BYTES,
   hitRecordBytes: HIT_RECORD_BYTES,
   sceneObjectRecordBytes: SCENE_OBJECT_RECORD_BYTES,
@@ -5783,11 +5793,11 @@ function resolveCanvas3(canvasOrSelector, documentRef = globalThis.document) {
   return fallback;
 }
 async function getPipelineDiagnostics(shaderModule) {
-  if (typeof shaderModule?.compilationInfo !== "function") {
+  if (typeof shaderModule?.getCompilationInfo !== "function") {
     return "";
   }
   try {
-    const info = await shaderModule.compilationInfo();
+    const info = await shaderModule.getCompilationInfo();
     const messages = info.messages ?? [];
     if (messages.length === 0) {
       return "";
@@ -5825,10 +5835,10 @@ ${diagnostics}` : "";
   }
 }
 async function assertShaderModuleCompiles(shaderModule, label) {
-  if (typeof shaderModule?.compilationInfo !== "function") {
+  if (typeof shaderModule?.getCompilationInfo !== "function") {
     return;
   }
-  const info = await shaderModule.compilationInfo();
+  const info = await shaderModule.getCompilationInfo();
   const messages = Array.isArray(info?.messages) ? info.messages : [];
   const errors = messages.filter((message) => message?.type === "error");
   if (errors.length <= 0) {
@@ -5862,7 +5872,28 @@ function createWavefrontDeviceDescriptor(adapter, options = {}) {
       TRACE_STORAGE_BUFFER_BINDINGS
     );
   }
+  const exposedSampledTextureLimit = Number(adapter?.limits?.maxSampledTexturesPerShaderStage);
+  if (Number.isFinite(exposedSampledTextureLimit)) {
+    if (exposedSampledTextureLimit < TRACE_SAMPLED_TEXTURE_BINDINGS) {
+      throw new Error(
+        `Wavefront material tracing requires maxSampledTexturesPerShaderStage>=${TRACE_SAMPLED_TEXTURE_BINDINGS}, but this adapter exposes ${exposedSampledTextureLimit}.`
+      );
+    }
+    requiredLimits.maxSampledTexturesPerShaderStage = Math.max(
+      Number(requiredLimits.maxSampledTexturesPerShaderStage ?? 0),
+      TRACE_SAMPLED_TEXTURE_BINDINGS
+    );
+  }
   const descriptor = { ...options.deviceDescriptor ?? {} };
+  const requiredFeatures = Array.from(descriptor.requiredFeatures ?? []);
+  const adapterFeatures = adapter?.features;
+  const timestampQuerySupported = typeof adapterFeatures?.has === "function" ? adapterFeatures.has("timestamp-query") : adapterFeatures && typeof adapterFeatures[Symbol.iterator] === "function" ? Array.from(adapterFeatures).includes("timestamp-query") : false;
+  if (options.gpuTimestamps !== false && timestampQuerySupported && !requiredFeatures.includes("timestamp-query")) {
+    requiredFeatures.push("timestamp-query");
+  }
+  if (requiredFeatures.length > 0) {
+    descriptor.requiredFeatures = requiredFeatures;
+  }
   if (Object.keys(requiredLimits).length > 0) {
     descriptor.requiredLimits = {
       ...descriptor.requiredLimits ?? {},
@@ -6052,6 +6083,376 @@ async function waitForSubmittedGpuWork(device, options = {}) {
   }
 }
 
+// src/wavefront-frame-telemetry.js
+var TIMESTAMP_QUERY_COUNT = 2;
+var TIMESTAMP_BUFFER_BYTES = TIMESTAMP_QUERY_COUNT * BigUint64Array.BYTES_PER_ELEMENT;
+function hasGpuFeature(features, name) {
+  if (typeof features?.has === "function") {
+    return features.has(name);
+  }
+  if (features && typeof features[Symbol.iterator] === "function") {
+    return Array.from(features).includes(name);
+  }
+  return false;
+}
+function freezeRayCountTelemetry(values = {}) {
+  return Object.freeze({
+    status: values.status ?? "not-requested",
+    source: values.source ?? null,
+    expectedPrimaryRays: values.expectedPrimaryRays ?? null,
+    observedPrimaryRays: values.observedPrimaryRays ?? null,
+    secondaryRays: values.secondaryRays ?? null,
+    totalPathSegments: values.totalPathSegments ?? null,
+    bounceHistogram: Object.freeze([...values.bounceHistogram ?? []]),
+    capturedRayCounts: values.capturedRayCounts ?? 0,
+    expectedRayCounts: values.expectedRayCounts ?? 0,
+    reason: values.reason ?? null
+  });
+}
+function createWavefrontRayCountTelemetry(values = {}) {
+  return freezeRayCountTelemetry(values);
+}
+function createWavefrontFrameTimingTelemetry(values = {}) {
+  return Object.freeze({
+    status: values.status ?? "not-requested",
+    source: values.source ?? null,
+    timestampQueryStatus: values.timestampQueryStatus ?? "not-recorded",
+    totalGpuTimeMs: values.totalGpuTimeMs ?? null,
+    totalRenderJobTimeMs: Math.max(0, Number(values.totalRenderJobTimeMs ?? 0)),
+    classificationTimeMs: values.classificationTimeMs ?? null,
+    compactionTimeMs: values.compactionTimeMs ?? null,
+    samplingTimeMs: values.samplingTimeMs ?? null,
+    reason: values.reason ?? null
+  });
+}
+function safeErrorReason(error) {
+  return error instanceof Error && error.message ? error.message : "unknown-telemetry-readback-failure";
+}
+function timestampDurationMs(values) {
+  if (values.length < TIMESTAMP_QUERY_COUNT || values[1] < values[0]) {
+    return null;
+  }
+  const durationNanoseconds = values[1] - values[0];
+  const durationMs = Number(durationNanoseconds) / 1e6;
+  return Number.isFinite(durationMs) && durationMs >= 0 ? durationMs : null;
+}
+function createWavefrontFrameTelemetryResources({
+  device,
+  constants,
+  maxRayCountRecords
+}) {
+  const rayRecordCapacity = Math.max(1, Math.trunc(Number(maxRayCountRecords) || 1));
+  const rayBufferBytes = rayRecordCapacity * Uint32Array.BYTES_PER_ELEMENT;
+  const mapMode = constants.map;
+  if (!mapMode || typeof mapMode.READ !== "number") {
+    return Object.freeze({
+      available: false,
+      reason: "gpu-map-read-unavailable",
+      memoryBytes: 0,
+      beginFrame() {
+      },
+      recordActiveRayCount() {
+      },
+      decorateFirstPass(descriptor) {
+        return descriptor;
+      },
+      decorateFinalPass(descriptor) {
+        return descriptor;
+      },
+      async readFrame({ expectedPrimaryRays = 0, expectedRayCounts = 0 } = {}) {
+        return Object.freeze({
+          rayCounts: freezeRayCountTelemetry({
+            status: "unavailable",
+            expectedPrimaryRays,
+            expectedRayCounts,
+            reason: "gpu-map-read-unavailable"
+          }),
+          timestampQueryStatus: "unsupported",
+          totalGpuTimeMs: null,
+          reason: "gpu-map-read-unavailable"
+        });
+      },
+      destroy() {
+      }
+    });
+  }
+  const rayCountBuffer = createBuffer(
+    device,
+    constants.buffer.COPY_DST | constants.buffer.COPY_SRC,
+    rayBufferBytes,
+    "plasius.wavefront.rayCounts"
+  );
+  const rayCountReadbackBuffer = createBuffer(
+    device,
+    constants.buffer.COPY_DST | constants.buffer.MAP_READ,
+    rayBufferBytes,
+    "plasius.wavefront.rayCounts.readback"
+  );
+  const timestampFeatureAvailable = hasGpuFeature(device?.features, "timestamp-query");
+  const timestampApiAvailable = timestampFeatureAvailable && typeof device.createQuerySet === "function" && typeof constants.buffer.QUERY_RESOLVE === "number";
+  let timestampQuerySet = null;
+  let timestampResolveBuffer = null;
+  let timestampReadbackBuffer = null;
+  let timestampSetupReason = timestampFeatureAvailable ? "timestamp-query-api-unavailable" : "timestamp-query-unsupported";
+  if (timestampApiAvailable) {
+    try {
+      timestampQuerySet = device.createQuerySet({
+        label: "plasius.wavefront.timestamps",
+        type: "timestamp",
+        count: TIMESTAMP_QUERY_COUNT
+      });
+      timestampResolveBuffer = createBuffer(
+        device,
+        constants.buffer.QUERY_RESOLVE | constants.buffer.COPY_SRC,
+        TIMESTAMP_BUFFER_BYTES,
+        "plasius.wavefront.timestamps.resolve"
+      );
+      timestampReadbackBuffer = createBuffer(
+        device,
+        constants.buffer.COPY_DST | constants.buffer.MAP_READ,
+        TIMESTAMP_BUFFER_BYTES,
+        "plasius.wavefront.timestamps.readback"
+      );
+      timestampSetupReason = null;
+    } catch (error) {
+      timestampQuerySet?.destroy?.();
+      timestampQuerySet = null;
+      timestampResolveBuffer?.destroy?.();
+      timestampResolveBuffer = null;
+      timestampReadbackBuffer?.destroy?.();
+      timestampReadbackBuffer = null;
+      timestampSetupReason = `timestamp-query-setup-failed:${safeErrorReason(error)}`;
+    }
+  }
+  const timestampUnavailableStatus = timestampSetupReason?.startsWith(
+    "timestamp-query-setup-failed:"
+  ) ? "failed" : "unsupported";
+  let active = false;
+  let recordCount = 0;
+  let recordOverflow = false;
+  let bounceIndices = [];
+  let timestampStarted = false;
+  let timestampEnded = false;
+  let rayReadbackMapped = false;
+  let timestampReadbackMapped = false;
+  const memoryBytes = rayBufferBytes * 2 + (timestampQuerySet ? TIMESTAMP_BUFFER_BYTES * 2 : 0);
+  function beginFrame() {
+    active = true;
+    recordCount = 0;
+    recordOverflow = false;
+    bounceIndices = [];
+    timestampStarted = false;
+    timestampEnded = false;
+  }
+  function recordActiveRayCount(encoder, counterBuffer, bounceIndex) {
+    if (!active) {
+      return;
+    }
+    if (recordCount >= rayRecordCapacity) {
+      recordOverflow = true;
+      return;
+    }
+    encoder.copyBufferToBuffer(
+      counterBuffer,
+      0,
+      rayCountBuffer,
+      recordCount * Uint32Array.BYTES_PER_ELEMENT,
+      Uint32Array.BYTES_PER_ELEMENT
+    );
+    bounceIndices.push(Math.max(0, Math.trunc(Number(bounceIndex) || 0)));
+    recordCount += 1;
+  }
+  function decorateFirstPass(descriptor) {
+    if (!active || !timestampQuerySet || timestampStarted) {
+      return descriptor;
+    }
+    timestampStarted = true;
+    return {
+      ...descriptor,
+      timestampWrites: {
+        querySet: timestampQuerySet,
+        beginningOfPassWriteIndex: 0
+      }
+    };
+  }
+  function decorateFinalPass(descriptor) {
+    if (!active || !timestampQuerySet || !timestampStarted || timestampEnded) {
+      return descriptor;
+    }
+    timestampEnded = true;
+    return {
+      ...descriptor,
+      timestampWrites: {
+        querySet: timestampQuerySet,
+        endOfPassWriteIndex: 1
+      }
+    };
+  }
+  async function readFrame({
+    expectedPrimaryRays = 0,
+    expectedRayCounts = recordCount,
+    waitForSubmittedGpuWork: waitForSubmittedGpuWork2
+  } = {}) {
+    active = false;
+    if (recordOverflow || recordCount !== expectedRayCounts) {
+      return Object.freeze({
+        rayCounts: freezeRayCountTelemetry({
+          status: "failed",
+          expectedPrimaryRays,
+          capturedRayCounts: recordCount,
+          expectedRayCounts,
+          reason: recordOverflow ? "ray-count-record-capacity-exceeded" : `ray-count-record-mismatch:${recordCount}/${expectedRayCounts}`
+        }),
+        timestampQueryStatus: timestampQuerySet ? "failed" : timestampUnavailableStatus,
+        totalGpuTimeMs: null,
+        reason: "ray-count-recording-incomplete"
+      });
+    }
+    const encoder = device.createCommandEncoder({
+      label: "plasius.wavefront.telemetry.readback"
+    });
+    const rayCopyBytes = Math.max(
+      Uint32Array.BYTES_PER_ELEMENT,
+      recordCount * Uint32Array.BYTES_PER_ELEMENT
+    );
+    encoder.copyBufferToBuffer(rayCountBuffer, 0, rayCountReadbackBuffer, 0, rayCopyBytes);
+    const canResolveTimestamps = timestampQuerySet && timestampStarted && timestampEnded && typeof encoder.resolveQuerySet === "function";
+    if (canResolveTimestamps) {
+      encoder.resolveQuerySet(
+        timestampQuerySet,
+        0,
+        TIMESTAMP_QUERY_COUNT,
+        timestampResolveBuffer,
+        0
+      );
+      encoder.copyBufferToBuffer(
+        timestampResolveBuffer,
+        0,
+        timestampReadbackBuffer,
+        0,
+        TIMESTAMP_BUFFER_BYTES
+      );
+    }
+    device.queue.submit([encoder.finish()]);
+    try {
+      await waitForSubmittedGpuWork2({
+        timeoutMs: GPU_READBACK_COMPLETION_TIMEOUT_MS,
+        allowTimeout: false
+      });
+      await rayCountReadbackBuffer.mapAsync(mapMode.READ);
+      rayReadbackMapped = true;
+      const rayCopy = rayCountReadbackBuffer.getMappedRange().slice(0, rayCopyBytes);
+      const rayCounts = new Uint32Array(rayCopy, 0, recordCount);
+      rayCountReadbackBuffer.unmap();
+      rayReadbackMapped = false;
+      let maximumBounceIndex = 0;
+      for (const bounceIndex of bounceIndices) {
+        maximumBounceIndex = Math.max(maximumBounceIndex, bounceIndex);
+      }
+      const bounceHistogram = Array.from({ length: maximumBounceIndex + 1 }, () => 0);
+      let observedPrimaryRays = 0;
+      let secondaryRays = 0;
+      let totalPathSegments = 0;
+      for (let index = 0; index < rayCounts.length; index += 1) {
+        const count = Number(rayCounts[index] ?? 0);
+        const bounceIndex = bounceIndices[index] ?? 0;
+        bounceHistogram[bounceIndex] = (bounceHistogram[bounceIndex] ?? 0) + count;
+        totalPathSegments += count;
+        if (bounceIndex === 0) {
+          observedPrimaryRays += count;
+        } else {
+          secondaryRays += count;
+        }
+      }
+      const primaryCountsMatch = observedPrimaryRays === expectedPrimaryRays;
+      const rayTelemetry = freezeRayCountTelemetry({
+        status: primaryCountsMatch ? "available" : "failed",
+        source: "gpu-active-queue-readback",
+        expectedPrimaryRays,
+        observedPrimaryRays,
+        secondaryRays: primaryCountsMatch ? secondaryRays : null,
+        totalPathSegments: primaryCountsMatch ? totalPathSegments : null,
+        bounceHistogram,
+        capturedRayCounts: recordCount,
+        expectedRayCounts,
+        reason: primaryCountsMatch ? null : `primary-ray-count-mismatch:${observedPrimaryRays}/${expectedPrimaryRays}`
+      });
+      let timestampQueryStatus = timestampQuerySet ? "failed" : timestampUnavailableStatus;
+      let totalGpuTimeMs = null;
+      let timestampReason = timestampSetupReason;
+      if (canResolveTimestamps) {
+        try {
+          await timestampReadbackBuffer.mapAsync(mapMode.READ);
+          timestampReadbackMapped = true;
+          const timestampCopy = timestampReadbackBuffer.getMappedRange().slice(0, TIMESTAMP_BUFFER_BYTES);
+          const timestamps = new BigUint64Array(timestampCopy);
+          timestampReadbackBuffer.unmap();
+          timestampReadbackMapped = false;
+          totalGpuTimeMs = timestampDurationMs(timestamps);
+          timestampQueryStatus = totalGpuTimeMs === null ? "failed" : "available";
+          timestampReason = totalGpuTimeMs === null ? "timestamp-query-returned-invalid-range" : null;
+        } catch (error) {
+          if (timestampReadbackMapped) {
+            timestampReadbackBuffer.unmap();
+            timestampReadbackMapped = false;
+          }
+          timestampQueryStatus = "failed";
+          timestampReason = `timestamp-query-readback-failed:${safeErrorReason(error)}`;
+        }
+      } else if (timestampQuerySet) {
+        timestampReason = "timestamp-query-span-incomplete";
+      }
+      return Object.freeze({
+        rayCounts: rayTelemetry,
+        timestampQueryStatus,
+        totalGpuTimeMs,
+        reason: timestampReason
+      });
+    } catch (error) {
+      if (rayReadbackMapped) {
+        rayCountReadbackBuffer.unmap();
+        rayReadbackMapped = false;
+      }
+      if (timestampReadbackMapped) {
+        timestampReadbackBuffer?.unmap();
+        timestampReadbackMapped = false;
+      }
+      const reason = safeErrorReason(error);
+      return Object.freeze({
+        rayCounts: freezeRayCountTelemetry({
+          status: "failed",
+          expectedPrimaryRays,
+          capturedRayCounts: recordCount,
+          expectedRayCounts,
+          reason: `ray-count-readback-failed:${reason}`
+        }),
+        timestampQueryStatus: timestampQuerySet ? "failed" : timestampUnavailableStatus,
+        totalGpuTimeMs: null,
+        reason: `telemetry-readback-failed:${reason}`
+      });
+    }
+  }
+  function destroy() {
+    active = false;
+    rayCountBuffer.destroy?.();
+    rayCountReadbackBuffer.destroy?.();
+    timestampQuerySet?.destroy?.();
+    timestampResolveBuffer?.destroy?.();
+    timestampReadbackBuffer?.destroy?.();
+  }
+  return Object.freeze({
+    available: true,
+    reason: null,
+    memoryBytes,
+    beginFrame,
+    recordActiveRayCount,
+    decorateFirstPass,
+    decorateFinalPass,
+    readFrame,
+    destroy
+  });
+}
+
 // src/wavefront-frame-stats.js
 function resolveWavefrontRenderedSamplesPerPixel({
   config,
@@ -6149,6 +6550,11 @@ function createWavefrontFrameStats({
       maxFramePassesPerSubmission: config.maxFramePassesPerSubmission,
       screenRays: config.width * config.height,
       primaryRays: config.width * config.height * renderedSamplesPerPixel,
+      secondaryRays: null,
+      totalPathSegments: null,
+      rayCounts: createWavefrontRayCountTelemetry(),
+      timings: createWavefrontFrameTimingTelemetry(),
+      telemetryMemoryBytes: 0,
       sceneObjectCount: config.sceneObjectCount,
       triangleCount: config.triangleCount,
       emissiveTriangleCount: config.emissiveTriangleCount,
@@ -6191,7 +6597,8 @@ function createWavefrontFrameEncoder({
   denoiseDirectResolveBindGroup,
   presentPipeline,
   presentBindGroup,
-  context
+  context,
+  getFrameTelemetry = () => null
 }) {
   const resolveConfig = resolveGetter(getConfig);
   const resolveBindGroups = resolveGetter(getBindGroups);
@@ -6199,9 +6606,12 @@ function createWavefrontFrameEncoder({
     encodeTileSample(encoder, tile, configOffset, parallelism) {
       const config = resolveConfig();
       const bindGroups = resolveBindGroups();
-      const generatePass = encoder.beginComputePass({
-        label: "plasius.wavefront.generatePrimaryRaysPass"
-      });
+      const frameTelemetry = getFrameTelemetry();
+      const generatePass = encoder.beginComputePass(
+        frameTelemetry?.decorateFirstPass({
+          label: "plasius.wavefront.generatePrimaryRaysPass"
+        }) ?? { label: "plasius.wavefront.generatePrimaryRaysPass" }
+      );
       const tileWorkgroups = Math.ceil(tile.width * tile.height / WORKGROUP_SIZE);
       generatePass.setBindGroup(0, bindGroups[0], [configOffset]);
       generatePass.setPipeline(pipelines.generatePrimaryRays);
@@ -6209,6 +6619,7 @@ function createWavefrontFrameEncoder({
       recordDirectDispatch(parallelism, [tileWorkgroups], WORKGROUP_SIZE);
       generatePass.end();
       for (let bounceIndex = 0; bounceIndex < config.maxDepth; bounceIndex += 1) {
+        frameTelemetry?.recordActiveRayCount(encoder, counterBuffer, bounceIndex);
         encoder.copyBufferToBuffer(
           counterBuffer,
           COUNTER_DISPATCH_ARGS_OFFSET,
@@ -6285,7 +6696,7 @@ function createWavefrontFrameEncoder({
     },
     encodePresent(encoder) {
       const texture = context.getCurrentTexture();
-      const passEncoder = encoder.beginRenderPass({
+      const descriptor = {
         label: "plasius.wavefront.presentPass",
         colorAttachments: [
           {
@@ -6295,7 +6706,10 @@ function createWavefrontFrameEncoder({
             storeOp: "store"
           }
         ]
-      });
+      };
+      const passEncoder = encoder.beginRenderPass(
+        getFrameTelemetry()?.decorateFinalPass(descriptor) ?? descriptor
+      );
       passEncoder.setPipeline(presentPipeline);
       passEncoder.setBindGroup(0, presentBindGroup);
       passEncoder.draw(3);
@@ -6595,36 +7009,49 @@ fn prepareMeshTrianglesAndLeaves(@builtin(global_invocation_id) globalId: vec3<u
   let uv1 = select(vec2<f32>(0.0), vertex1.uv.xy, vertex1.uv.z > 0.5);
   let uv2 = select(vec2<f32>(0.0), vertex2.uv.xy, vertex2.uv.z > 0.5);
 
-  triangles[triangleIndex] = TriangleRecord(
-    triangleIndex,
-    mesh.meshId,
-    mesh.materialKind,
-    mesh.flags,
-    mesh.materialRefId,
-    mesh.mediumRefId,
-    mesh.materialSlot,
-    0u,
-    vec4<f32>(vertex0.position.xyz, 0.0),
-    vec4<f32>(vertex1.position.xyz, 0.0),
-    vec4<f32>(vertex2.position.xyz, 0.0),
-    vec4<f32>(n0, 0.0),
-    vec4<f32>(n1, 0.0),
-    vec4<f32>(n2, 0.0),
-    vec4<f32>(uv0, uv1),
-    vec4<f32>(uv2, 0.0, 0.0),
-    mesh.color,
-    mesh.emission,
-    mesh.material,
-    mesh.materialResponse,
-    mesh.materialExtension,
-    mesh.specularColor,
-    mesh.baseColorAtlas,
-    mesh.metallicRoughnessAtlas,
-    mesh.normalAtlas,
-    mesh.occlusionAtlas,
-    mesh.emissiveAtlas,
-    mesh.textureSettings
-  );
+  var preparedTriangle = TriangleRecord();
+  preparedTriangle.triangleId = triangleIndex;
+  preparedTriangle.meshId = mesh.meshId;
+  preparedTriangle.materialKind = mesh.materialKind;
+  preparedTriangle.flags = mesh.flags;
+  preparedTriangle.materialRefId = mesh.materialRefId;
+  preparedTriangle.mediumRefId = mesh.mediumRefId;
+  preparedTriangle.materialSlot = mesh.materialSlot;
+  preparedTriangle.v0 = vec4<f32>(vertex0.position.xyz, 0.0);
+  preparedTriangle.v1 = vec4<f32>(vertex1.position.xyz, 0.0);
+  preparedTriangle.v2 = vec4<f32>(vertex2.position.xyz, 0.0);
+  preparedTriangle.n0 = vec4<f32>(n0, 0.0);
+  preparedTriangle.n1 = vec4<f32>(n1, 0.0);
+  preparedTriangle.n2 = vec4<f32>(n2, 0.0);
+  preparedTriangle.uv0uv1 = vec4<f32>(uv0, uv1);
+  preparedTriangle.uv2Pad = vec4<f32>(uv2, 0.0, 0.0);
+  preparedTriangle.color = mesh.color;
+  preparedTriangle.emission = mesh.emission;
+  preparedTriangle.material = mesh.material;
+  preparedTriangle.materialResponse = mesh.materialResponse;
+  preparedTriangle.materialExtension = mesh.materialExtension;
+  preparedTriangle.specularColor = mesh.specularColor;
+  preparedTriangle.baseColorAtlas = mesh.baseColorAtlas;
+  preparedTriangle.metallicRoughnessAtlas = mesh.metallicRoughnessAtlas;
+  preparedTriangle.normalAtlas = mesh.normalAtlas;
+  preparedTriangle.occlusionAtlas = mesh.occlusionAtlas;
+  preparedTriangle.emissiveAtlas = mesh.emissiveAtlas;
+  preparedTriangle.textureSettings = mesh.textureSettings;
+  preparedTriangle.materialExtension2 = vec4<f32>(0.0, 0.0, 1.3, 0.0);
+  preparedTriangle.materialExtension3 = vec4<f32>(100.0, 400.0, 0.0, 0.0);
+  preparedTriangle.clearcoatAtlas = vec4<f32>(0.0, 0.0, 1.0, 1.0);
+  preparedTriangle.clearcoatRoughnessAtlas = vec4<f32>(0.0, 0.0, 1.0, 1.0);
+  preparedTriangle.clearcoatNormalAtlas = vec4<f32>(0.0, 0.0, 1.0, 1.0);
+  preparedTriangle.transmissionAtlas = vec4<f32>(0.0, 0.0, 1.0, 1.0);
+  preparedTriangle.thicknessAtlas = vec4<f32>(0.0, 0.0, 1.0, 1.0);
+  preparedTriangle.sheenColorAtlas = vec4<f32>(0.0, 0.0, 1.0, 1.0);
+  preparedTriangle.sheenRoughnessAtlas = vec4<f32>(0.0, 0.0, 1.0, 1.0);
+  preparedTriangle.specularAtlas = vec4<f32>(0.0, 0.0, 1.0, 1.0);
+  preparedTriangle.specularColorAtlas = vec4<f32>(0.0, 0.0, 1.0, 1.0);
+  preparedTriangle.iridescenceAtlas = vec4<f32>(0.0, 0.0, 1.0, 1.0);
+  preparedTriangle.iridescenceThicknessAtlas = vec4<f32>(0.0, 0.0, 1.0, 1.0);
+  preparedTriangle.anisotropyAtlas = vec4<f32>(0.0, 0.0, 1.0, 1.0);
+  triangles[triangleIndex] = preparedTriangle;
 
   let leafBase = config.triangleCount - 1u;
   let nodeIndex = leafBase + triangleIndex;
@@ -7294,36 +7721,7 @@ fn intersectActiveQueue(@builtin(global_invocation_id) globalId: vec3<u32>) {
     vec4<f32>(1.0, 1.0, 1.0, 1.0)
   );
   var candidate = no_candidate();
-  var hitTriangle = TriangleRecord(
-    0u,
-    0u,
-    0u,
-    0u,
-    0u,
-    0u,
-    0u,
-    0u,
-    vec4<f32>(0.0),
-    vec4<f32>(0.0),
-    vec4<f32>(0.0),
-    vec4<f32>(0.0, 1.0, 0.0, 0.0),
-    vec4<f32>(0.0, 1.0, 0.0, 0.0),
-    vec4<f32>(0.0, 1.0, 0.0, 0.0),
-    vec4<f32>(0.0),
-    vec4<f32>(0.0),
-    vec4<f32>(0.0),
-    vec4<f32>(0.0),
-    vec4<f32>(1.0, 0.0, 1.0, 1.0),
-    vec4<f32>(0.0, 0.0, 0.0, 0.08),
-    vec4<f32>(0.08, 1.0, 0.0, 0.0),
-    vec4<f32>(1.0, 1.0, 1.0, 1.0),
-    vec4<f32>(0.0, 0.0, 1.0, 1.0),
-    vec4<f32>(0.0, 0.0, 1.0, 1.0),
-    vec4<f32>(0.0, 0.0, 1.0, 1.0),
-    vec4<f32>(0.0, 0.0, 1.0, 1.0),
-    vec4<f32>(0.0, 0.0, 1.0, 1.0),
-    vec4<f32>(1.0, 1.0, 1.0, 0.0)
-  );
+  var hitTriangle = TriangleRecord();
 
   for (var objectIndex = 0u; objectIndex < config.sceneObjectCount; objectIndex = objectIndex + 1u) {
     let object = sceneObjects[objectIndex];
@@ -10198,7 +10596,19 @@ function createWavefrontBindGroupLayouts(device, constants) {
       { binding: 29, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
       { binding: 30, visibility: constants.shader.COMPUTE, sampler: { type: "filtering" } },
       { binding: 31, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
-      { binding: 32, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } }
+      { binding: 32, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
+      { binding: 33, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
+      { binding: 34, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
+      { binding: 35, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
+      { binding: 36, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
+      { binding: 37, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
+      { binding: 38, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
+      { binding: 39, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
+      { binding: 40, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
+      { binding: 41, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
+      { binding: 42, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
+      { binding: 43, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } },
+      { binding: 44, visibility: constants.shader.COMPUTE, texture: { sampleType: "float" } }
     ]
   });
   const acceleration = device.createBindGroupLayout({
@@ -11186,6 +11596,8 @@ async function createWavefrontPathTracingComputeRenderer(options = {}) {
     outputView,
     sampler
   });
+  let activeFrameTelemetry = null;
+  let frameTelemetryResources = null;
   const frameEncoder = createWavefrontFrameEncoder({
     getConfig: () => config,
     getBindGroups: () => bindGroups,
@@ -11197,7 +11609,8 @@ async function createWavefrontPathTracingComputeRenderer(options = {}) {
     denoiseDirectResolveBindGroup,
     presentPipeline,
     presentBindGroup,
-    context
+    context,
+    getFrameTelemetry: () => activeFrameTelemetry
   });
   let frame = 0;
   let accelerationBuilt = !config.gpuAccelerationBuildRequired;
@@ -11210,6 +11623,16 @@ async function createWavefrontPathTracingComputeRenderer(options = {}) {
     createGpuParallelismCounters()
   );
   const waitForSubmittedGpuWork2 = (waitOptions = {}) => waitForSubmittedGpuWork(device, waitOptions);
+  function ensureFrameTelemetryResources() {
+    if (!frameTelemetryResources) {
+      frameTelemetryResources = createWavefrontFrameTelemetryResources({
+        device,
+        constants,
+        maxRayCountRecords: tiles.length * config.samplesPerPixel * config.maxDepth
+      });
+    }
+    return frameTelemetryResources;
+  }
   function resolveRenderedSamplesPerPixel(renderOptions = {}, awaitGPUCompletion = true) {
     return resolveWavefrontRenderedSamplesPerPixel({
       config,
@@ -11337,7 +11760,13 @@ async function createWavefrontPathTracingComputeRenderer(options = {}) {
         frameSubmissionCount + (accelerationBuildSubmitted ? 1 : 0),
         frameTimeMs,
         false
-      )
+      ),
+      timings: createWavefrontFrameTimingTelemetry({
+        status: "not-requested",
+        source: "cpu-submit",
+        timestampQueryStatus: "not-recorded",
+        totalRenderJobTimeMs: frameTimeMs
+      })
     });
   }
   function dispatchFrameAwaitingGpu(frameIndex, parallelism, renderedSamplesPerPixel = config.samplesPerPixel, optionsForFrame = {}) {
@@ -11367,98 +11796,151 @@ async function createWavefrontPathTracingComputeRenderer(options = {}) {
     const awaitGPUCompletion = renderOptions.awaitGPUCompletion !== false;
     const samplingPlan = resolveRenderedSamplesPerPixel(renderOptions, awaitGPUCompletion);
     const useThrottledHighSamplePath = awaitGPUCompletion && samplingPlan.renderedSamplesPerPixel >= 8;
+    const telemetryRequested = renderOptions.readStats === true;
+    const telemetryCanRecord = telemetryRequested && awaitGPUCompletion;
+    const telemetryResourcesForFrame = telemetryCanRecord ? ensureFrameTelemetryResources() : null;
+    if (telemetryResourcesForFrame?.available) {
+      telemetryResourcesForFrame.beginFrame();
+      activeFrameTelemetry = telemetryResourcesForFrame;
+    }
     const frameStartTimeMs = nowMs3();
     let frameStats;
-    if (useThrottledHighSamplePath) {
-      frame += 1;
-      const frameIndex = frame + config.frameIndex;
-      const parallelismCounters = createGpuParallelismCounters();
-      const accelerationBuildSubmitted = dispatchGpuAccelerationBuild(frameIndex, parallelismCounters);
-      let frameSubmissionCount = 0;
-      let frameConfigSlot = 0;
-      if (accelerationBuildSubmitted) {
-        const accelerationWaitOptions = {
-          ...estimateSubmittedGpuWorkTiming(
-            { ...config, renderedSamplesPerPixel: 1 },
-            1,
-            renderOptions.submittedWorkTimeoutMs,
-            { includeAccelerationBuild: true }
-          ),
-          allowTimeout: false
-        };
-        await waitForSubmittedGpuWork2(accelerationWaitOptions);
-      }
-      for (let tileIndex = 0; tileIndex < tiles.length; tileIndex += 1) {
-        const tileRangeDispatch = dispatchFrameAwaitingGpu(
-          frameIndex,
-          parallelismCounters,
-          samplingPlan.renderedSamplesPerPixel,
-          {
-            sampleRangeStart: 0,
-            sampleRangeEnd: samplingPlan.renderedSamplesPerPixel,
-            tileStartIndex: tileIndex,
-            tileEndIndex: tileIndex + 1,
-            startingSubmissionCount: frameSubmissionCount,
-            startingSlot: frameConfigSlot,
-            includeDenoise: tileIndex + 1 >= tiles.length,
-            includePresent: tileIndex + 1 >= tiles.length
-          }
-        );
-        frameSubmissionCount = tileRangeDispatch.submissionCount;
-        frameConfigSlot = tileRangeDispatch.slot;
-        const tileWaitOptions = {
-          ...estimateSubmittedGpuWorkTiming(
-            { ...config, renderedSamplesPerPixel: samplingPlan.renderedSamplesPerPixel },
-            1,
-            renderOptions.submittedWorkTimeoutMs,
+    try {
+      if (useThrottledHighSamplePath) {
+        frame += 1;
+        const frameIndex = frame + config.frameIndex;
+        const parallelismCounters = createGpuParallelismCounters();
+        const accelerationBuildSubmitted = dispatchGpuAccelerationBuild(frameIndex, parallelismCounters);
+        let frameSubmissionCount = 0;
+        let frameConfigSlot = 0;
+        if (accelerationBuildSubmitted) {
+          const accelerationWaitOptions = {
+            ...estimateSubmittedGpuWorkTiming(
+              { ...config, renderedSamplesPerPixel: 1 },
+              1,
+              renderOptions.submittedWorkTimeoutMs,
+              { includeAccelerationBuild: true }
+            ),
+            allowTimeout: false
+          };
+          await waitForSubmittedGpuWork2(accelerationWaitOptions);
+        }
+        for (let tileIndex = 0; tileIndex < tiles.length; tileIndex += 1) {
+          const tileRangeDispatch = dispatchFrameAwaitingGpu(
+            frameIndex,
+            parallelismCounters,
+            samplingPlan.renderedSamplesPerPixel,
             {
-              includeDenoise: tileIndex + 1 >= tiles.length && config.denoise,
+              sampleRangeStart: 0,
+              sampleRangeEnd: samplingPlan.renderedSamplesPerPixel,
+              tileStartIndex: tileIndex,
+              tileEndIndex: tileIndex + 1,
+              startingSubmissionCount: frameSubmissionCount,
+              startingSlot: frameConfigSlot,
+              includeDenoise: tileIndex + 1 >= tiles.length,
               includePresent: tileIndex + 1 >= tiles.length
             }
-          ),
+          );
+          frameSubmissionCount = tileRangeDispatch.submissionCount;
+          frameConfigSlot = tileRangeDispatch.slot;
+          const tileWaitOptions = {
+            ...estimateSubmittedGpuWorkTiming(
+              { ...config, renderedSamplesPerPixel: samplingPlan.renderedSamplesPerPixel },
+              1,
+              renderOptions.submittedWorkTimeoutMs,
+              {
+                includeDenoise: tileIndex + 1 >= tiles.length && config.denoise,
+                includePresent: tileIndex + 1 >= tiles.length
+              }
+            ),
+            allowTimeout: false
+          };
+          await waitForSubmittedGpuWork2(tileWaitOptions);
+        }
+        frameStats = createFrameStats({
+          frameIndex,
+          accelerationBuildSubmitted,
+          frameSubmissionCount,
+          parallelismCounters,
+          renderedSamplesPerPixel: samplingPlan.renderedSamplesPerPixel,
+          targetSamplesPerPixel: samplingPlan.targetSamplesPerPixel,
+          frameTimeBudgetMs: samplingPlan.frameTimeBudgetMs,
+          budgetConstrained: samplingPlan.budgetConstrained
+        });
+      } else {
+        const submittedWorkTiming = estimateSubmittedGpuWorkTiming(
+          { ...config, renderedSamplesPerPixel: samplingPlan.renderedSamplesPerPixel },
+          tiles.length,
+          renderOptions.submittedWorkTimeoutMs,
+          { includeAccelerationBuild: config.gpuAccelerationBuildRequired && !accelerationBuilt }
+        );
+        const submissionWaitOptions = awaitGPUCompletion ? {
+          timeoutMs: submittedWorkTiming.timeoutMs,
+          maxWaitMs: submittedWorkTiming.maxWaitMs,
           allowTimeout: false
+        } : {
+          timeoutMs: submittedWorkTiming.timeoutMs,
+          maxWaitMs: submittedWorkTiming.maxWaitMs
         };
-        await waitForSubmittedGpuWork2(tileWaitOptions);
-      }
-      frameStats = createFrameStats({
-        frameIndex,
-        accelerationBuildSubmitted,
-        frameSubmissionCount,
-        parallelismCounters,
-        renderedSamplesPerPixel: samplingPlan.renderedSamplesPerPixel,
-        targetSamplesPerPixel: samplingPlan.targetSamplesPerPixel,
-        frameTimeBudgetMs: samplingPlan.frameTimeBudgetMs,
-        budgetConstrained: samplingPlan.budgetConstrained
-      });
-    } else {
-      const submittedWorkTiming = estimateSubmittedGpuWorkTiming(
-        { ...config, renderedSamplesPerPixel: samplingPlan.renderedSamplesPerPixel },
-        tiles.length,
-        renderOptions.submittedWorkTimeoutMs,
-        { includeAccelerationBuild: config.gpuAccelerationBuildRequired && !accelerationBuilt }
-      );
-      const submissionWaitOptions = awaitGPUCompletion ? {
-        timeoutMs: submittedWorkTiming.timeoutMs,
-        maxWaitMs: submittedWorkTiming.maxWaitMs,
-        allowTimeout: false
-      } : {
-        timeoutMs: submittedWorkTiming.timeoutMs,
-        maxWaitMs: submittedWorkTiming.maxWaitMs
-      };
-      frameStats = renderOnce(renderOptions, samplingPlan);
-      if (awaitGPUCompletion) {
-        await waitForSubmittedGpuWork2(submissionWaitOptions);
+        frameStats = renderOnce(renderOptions, samplingPlan);
+        if (awaitGPUCompletion) {
+          await waitForSubmittedGpuWork2(submissionWaitOptions);
+        }
       }
+    } finally {
+      activeFrameTelemetry = null;
     }
     const frameTimeMs = Math.max(0, nowMs3() - frameStartTimeMs);
     if (awaitGPUCompletion) {
       lastCompletedFrameTimeMs = frameTimeMs;
       lastCompletedSamplesPerPixel = frameStats.renderedSamplesPerPixel ?? frameStats.samplesPerPixel;
     }
+    const expectedPrimaryRays = config.width * config.height * samplingPlan.renderedSamplesPerPixel;
+    const expectedRayCounts = tiles.length * samplingPlan.renderedSamplesPerPixel * config.maxDepth;
+    const telemetryReadback = telemetryCanRecord ? await telemetryResourcesForFrame.readFrame({
+      expectedPrimaryRays,
+      expectedRayCounts,
+      waitForSubmittedGpuWork: waitForSubmittedGpuWork2
+    }) : null;
+    const rayCounts = !telemetryRequested ? createWavefrontRayCountTelemetry() : !awaitGPUCompletion ? createWavefrontRayCountTelemetry({
+      status: "unavailable",
+      expectedPrimaryRays,
+      expectedRayCounts,
+      reason: "gpu-work-not-awaited"
+    }) : telemetryReadback.rayCounts;
+    const timings = !telemetryRequested ? createWavefrontFrameTimingTelemetry({
+      status: "not-requested",
+      source: awaitGPUCompletion ? "queue-completion" : "cpu-submit",
+      timestampQueryStatus: "not-recorded",
+      totalRenderJobTimeMs: frameTimeMs
+    }) : !awaitGPUCompletion ? createWavefrontFrameTimingTelemetry({
+      status: "unavailable",
+      source: "cpu-submit",
+      timestampQueryStatus: "not-recorded",
+      totalRenderJobTimeMs: frameTimeMs,
+      reason: "gpu-work-not-awaited"
+    }) : telemetryReadback.timestampQueryStatus === "available" ? createWavefrontFrameTimingTelemetry({
+      status: "available",
+      source: "timestamp-query",
+      timestampQueryStatus: "available",
+      totalGpuTimeMs: telemetryReadback.totalGpuTimeMs,
+      totalRenderJobTimeMs: frameTimeMs
+    }) : createWavefrontFrameTimingTelemetry({
+      status: "fallback",
+      source: "queue-completion",
+      timestampQueryStatus: telemetryReadback.timestampQueryStatus,
+      totalRenderJobTimeMs: frameTimeMs,
+      reason: telemetryReadback.reason
+    });
     const deviceLossStatus = awaitGPUCompletion ? "not-detected" : typeof device.lost?.then === "function" ? "pending" : "not-exposed";
     frameStats = Object.freeze({
       ...frameStats,
       deviceLossStatus,
+      secondaryRays: rayCounts.status === "available" ? rayCounts.secondaryRays : null,
+      totalPathSegments: rayCounts.status === "available" ? rayCounts.totalPathSegments : null,
+      rayCounts,
+      timings,
+      telemetryMemoryBytes: telemetryResourcesForFrame?.memoryBytes ?? 0,
       gpuWorkerJobs: createGpuWorkerJobDiagnostics(
         frameStats.gpuParallelism,
         frameStats.commandSubmissions,
@@ -11567,6 +12049,7 @@ async function createWavefrontPathTracingComputeRenderer(options = {}) {
     });
   }
   function destroy() {
+    frameTelemetryResources?.destroy?.();
     activeQueue.destroy?.();
     nextQueue.destroy?.();
     hitBuffer.destroy?.();