@plasius/gpu-renderer 0.2.40 → 0.2.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/gpu-renderer",
-  "version": "0.2.40",
+  "version": "0.2.42",
   "description": "Framework-agnostic WebGPU renderer runtime for Plasius projects.",
   "type": "module",
   "sideEffects": false,

package/src/index.d.ts

@@ -1011,6 +1011,8 @@ export interface CreateWavefrontPathTracingComputeRendererOptions {
   readonly navigator?: Navigator | { gpu?: GPU };
   readonly document?: Document;
   readonly deviceDescriptor?: GPUDeviceDescriptor;
+  /** Opportunistically request WebGPU timestamp-query support when exposed. Defaults to true. */
+  readonly gpuTimestamps?: boolean;
   readonly requiredLimits?: Partial<Record<string, number>>;
   readonly powerPreference?: GPUPowerPreference;
   readonly alpha?: boolean;
@@ -1122,6 +1124,31 @@ export interface WavefrontPathTracingComputeRenderer {
   destroy(): void;
 }
 
+export interface WavefrontRayCountTelemetry {
+  readonly status: "not-requested" | "available" | "unavailable" | "failed";
+  readonly source: "gpu-active-queue-readback" | null;
+  readonly expectedPrimaryRays: number | null;
+  readonly observedPrimaryRays: number | null;
+  readonly secondaryRays: number | null;
+  readonly totalPathSegments: number | null;
+  readonly bounceHistogram: readonly number[];
+  readonly capturedRayCounts: number;
+  readonly expectedRayCounts: number;
+  readonly reason: string | null;
+}
+
+export interface WavefrontFrameTimingTelemetry {
+  readonly status: "not-requested" | "available" | "fallback" | "unavailable" | "failed";
+  readonly source: "timestamp-query" | "queue-completion" | "cpu-submit" | null;
+  readonly timestampQueryStatus: "not-recorded" | "available" | "unsupported" | "failed";
+  readonly totalGpuTimeMs: number | null;
+  readonly totalRenderJobTimeMs: number;
+  readonly classificationTimeMs: number | null;
+  readonly compactionTimeMs: number | null;
+  readonly samplingTimeMs: number | null;
+  readonly reason: string | null;
+}
+
 export interface WavefrontPathTracingComputeFrameStats {
   readonly frame: number;
   readonly width: number;
@@ -1136,6 +1163,11 @@ export interface WavefrontPathTracingComputeFrameStats {
   readonly maxFramePassesPerSubmission: number;
   readonly screenRays: number;
   readonly primaryRays: number;
+  readonly secondaryRays: number | null;
+  readonly totalPathSegments: number | null;
+  readonly rayCounts: WavefrontRayCountTelemetry;
+  readonly timings: WavefrontFrameTimingTelemetry;
+  readonly telemetryMemoryBytes: number;
   readonly sceneObjectCount: number;
   readonly triangleCount: number;
   readonly emissiveTriangleCount: number;
@@ -1184,6 +1216,7 @@ export interface WavefrontPathTracingComputeFrameStats {
         invalidSamples: number;
         legacyClampEquivalentSamples: number;
       }>;
+      rayCountStatus: WavefrontRayCountTelemetry["status"];
       memory: Readonly<{
         totalBytes: number;
         breakdown: WavefrontPathTracingMemoryEstimate | null;
@@ -1418,6 +1451,7 @@ export const rendererWavefrontComputeStatsStride: 8;
 export const wavefrontPathTracingComputeLimits: Readonly<{
   workgroupSize: 64;
   traceStorageBufferBindings: number;
+  traceSampledTextureBindings: number;
   rayRecordBytes: 96;
   hitRecordBytes: 256;
   sceneObjectRecordBytes: 160;

package/src/wavefront-compute.js

@@ -50,6 +50,11 @@ import {
   createWavefrontFrameStats,
   resolveWavefrontRenderedSamplesPerPixel,
 } from "./wavefront-frame-stats.js";
+import {
+  createWavefrontFrameTelemetryResources,
+  createWavefrontFrameTimingTelemetry,
+  createWavefrontRayCountTelemetry,
+} from "./wavefront-frame-telemetry.js";
 import { createWavefrontFrameEncoder } from "./wavefront-frame-encoder.js";
 import {
   dispatchWavefrontFrame,
@@ -573,6 +578,8 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     outputView,
     sampler,
   });
+  let activeFrameTelemetry = null;
+  let frameTelemetryResources = null;
   const frameEncoder = createWavefrontFrameEncoder({
     getConfig: () => config,
     getBindGroups: () => bindGroups,
@@ -585,6 +592,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     presentPipeline,
     presentBindGroup,
     context,
+    getFrameTelemetry: () => activeFrameTelemetry,
   });
 
   let frame = 0;
@@ -600,6 +608,18 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
   const waitForSubmittedGpuWork = (waitOptions = {}) =>
     waitForSubmittedGpuWorkForDevice(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,
@@ -735,6 +755,12 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
         frameTimeMs,
         false
       ),
+      timings: createWavefrontFrameTimingTelemetry({
+        status: "not-requested",
+        source: "cpu-submit",
+        timestampQueryStatus: "not-recorded",
+        totalRenderJobTimeMs: frameTimeMs,
+      }),
     });
   }
 
@@ -773,96 +799,160 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     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 = nowMs();
     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 waitForSubmittedGpuWork(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 waitForSubmittedGpuWork(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,
             }
-          ),
-          allowTimeout: false,
-        };
-        await waitForSubmittedGpuWork(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,
+          );
+          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,
-          }
-        : {
-            timeoutMs: submittedWorkTiming.timeoutMs,
-            maxWaitMs: submittedWorkTiming.maxWaitMs,
           };
-      frameStats = renderOnce(renderOptions, samplingPlan);
-      if (awaitGPUCompletion) {
-        await waitForSubmittedGpuWork(submissionWaitOptions);
+          await waitForSubmittedGpuWork(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 waitForSubmittedGpuWork(submissionWaitOptions);
+        }
       }
+    } finally {
+      activeFrameTelemetry = null;
     }
     const frameTimeMs = Math.max(0, nowMs() - 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,
+        })
+      : 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"
@@ -872,6 +962,13 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     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,
@@ -991,6 +1088,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
   }
 
   function destroy() {
+    frameTelemetryResources?.destroy?.();
     activeQueue.destroy?.();
     nextQueue.destroy?.();
     hitBuffer.destroy?.();

package/src/wavefront-core.js

@@ -58,6 +58,7 @@ export const COUNTER_TRANSPORT_RESIDUAL_LUMINANCE_OFFSET = 22;
 export const COUNTER_TRANSPORT_ZERO_TERMINATION_OFFSET = 23;
 export const COUNTER_TRANSPORT_CHECKSUM_OFFSET = 24;
 export const TRACE_STORAGE_BUFFER_BINDINGS = 10;
+export const TRACE_SAMPLED_TEXTURE_BINDINGS = 21;
 export const BRDF_LUT_UPLOAD_CACHE = new Map();
 export const HIT_TYPE_SURFACE = 0;
 export const HIT_TYPE_EMISSIVE = 1;
@@ -130,6 +131,7 @@ export const EMPTY_TERMINATION_METRICS = Object.freeze({
 export const 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,

package/src/wavefront-frame-encoder.js

@@ -24,6 +24,7 @@ export function createWavefrontFrameEncoder({
   presentPipeline,
   presentBindGroup,
   context,
+  getFrameTelemetry = () => null,
 }) {
   const resolveConfig = resolveGetter(getConfig);
   const resolveBindGroups = resolveGetter(getBindGroups);
@@ -32,9 +33,12 @@ export 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]);
@@ -44,6 +48,7 @@ export function createWavefrontFrameEncoder({
       generatePass.end();
 
       for (let bounceIndex = 0; bounceIndex < config.maxDepth; bounceIndex += 1) {
+        frameTelemetry?.recordActiveRayCount(encoder, counterBuffer, bounceIndex);
         encoder.copyBufferToBuffer(
           counterBuffer,
           COUNTER_DISPATCH_ARGS_OFFSET,
@@ -125,7 +130,7 @@ export function createWavefrontFrameEncoder({
 
     encodePresent(encoder) {
       const texture = context.getCurrentTexture();
-      const passEncoder = encoder.beginRenderPass({
+      const descriptor = {
         label: "plasius.wavefront.presentPass",
         colorAttachments: [
           {
@@ -135,7 +140,10 @@ export function createWavefrontFrameEncoder({
             storeOp: "store",
           },
         ],
-      });
+      };
+      const passEncoder = encoder.beginRenderPass(
+        getFrameTelemetry()?.decorateFinalPass(descriptor) ?? descriptor
+      );
       passEncoder.setPipeline(presentPipeline);
       passEncoder.setBindGroup(0, presentBindGroup);
       passEncoder.draw(3);

package/src/wavefront-frame-runtime.js

@@ -184,6 +184,14 @@ export 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(
@@ -226,6 +234,21 @@ export function createWavefrontTransportGuardrailSummary(frameStats, options = {
           ? `${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"
@@ -249,6 +272,7 @@ export function createWavefrontTransportGuardrailSummary(frameStats, options = {
         invalidSamples,
         legacyClampEquivalentSamples,
       }),
+      rayCountStatus,
       memory,
     }),
     checks,

package/src/wavefront-frame-stats.js

@@ -4,6 +4,10 @@ import {
   clamp,
   readPositiveInteger,
 } from "./wavefront-core.js";
+import {
+  createWavefrontFrameTimingTelemetry,
+  createWavefrontRayCountTelemetry,
+} from "./wavefront-frame-telemetry.js";
 
 export function resolveWavefrontRenderedSamplesPerPixel({
   config,
@@ -107,6 +111,11 @@ export 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,