@plasius/gpu-debug 0.2.5 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -28,6 +28,7 @@ interface GpuDebugSessionOptions {
28
28
  maxRetainedDependencyUnlockSamples?: number;
29
29
  maxRetainedPipelinePhaseSamples?: number;
30
30
  maxRetainedWavefrontSamples?: number;
31
+ maxRetainedFixedSppSamples?: number;
31
32
  maxRetainedFrameSamples?: number;
32
33
  maxTrackedAllocations?: number;
33
34
  }
@@ -120,6 +121,57 @@ interface GpuWavefrontTelemetrySample {
120
121
  terminationReasons?: readonly GpuWavefrontTerminationSample[];
121
122
  signal?: AbortSignal;
122
123
  }
124
+ /** Availability state reported by the renderer for exact per-bounce ray counts. */
125
+ type GpuFixedSppRayCountStatus = "not-requested" | "available" | "unavailable" | "failed";
126
+ /** Timing evidence state reported by the renderer for one fixed-SPP frame. */
127
+ type GpuFixedSppTimingStatus = "not-requested" | "available" | "fallback" | "unavailable" | "failed";
128
+ /** Timestamp-query availability reported by the renderer. */
129
+ type GpuFixedSppTimestampQueryStatus = "not-recorded" | "available" | "unsupported" | "failed";
130
+ /** Exact, structurally compatible ray-count evidence from a renderer frame. */
131
+ interface GpuFixedSppRayCountTelemetry {
132
+ readonly status: GpuFixedSppRayCountStatus;
133
+ readonly source: "gpu-active-queue-readback" | null;
134
+ readonly expectedPrimaryRays: number | null;
135
+ readonly observedPrimaryRays: number | null;
136
+ readonly secondaryRays: number | null;
137
+ readonly totalPathSegments: number | null;
138
+ readonly bounceHistogram: readonly number[];
139
+ /** GPU counter records captured before records are collapsed into bounce buckets. */
140
+ readonly capturedRayCounts: number;
141
+ /** GPU counter records expected for the tile, sample, and depth schedule. */
142
+ readonly expectedRayCounts: number;
143
+ readonly reason: string | null;
144
+ }
145
+ /** Timing evidence from a fixed-SPP renderer frame. */
146
+ interface GpuFixedSppFrameTimingTelemetry {
147
+ readonly status: GpuFixedSppTimingStatus;
148
+ readonly source: "timestamp-query" | "queue-completion" | "cpu-submit" | null;
149
+ readonly timestampQueryStatus: GpuFixedSppTimestampQueryStatus;
150
+ readonly totalGpuTimeMs: number | null;
151
+ readonly totalRenderJobTimeMs: number;
152
+ readonly classificationTimeMs: number | null;
153
+ readonly compactionTimeMs: number | null;
154
+ readonly samplingTimeMs: number | null;
155
+ readonly reason: string | null;
156
+ }
157
+ /**
158
+ * Caller-reported fixed-SPP frame evidence. Recording this sample never starts a
159
+ * readback; callers pass an already-resolved renderer statistics snapshot.
160
+ */
161
+ interface GpuFixedSppTelemetrySample {
162
+ owner: string;
163
+ queueClass: GpuDebugQueueClass;
164
+ frameId?: string;
165
+ samplesPerPixel: number;
166
+ renderedSamplesPerPixel: number;
167
+ primaryRays: number;
168
+ secondaryRays: number | null;
169
+ totalPathSegments: number | null;
170
+ rayCounts: GpuFixedSppRayCountTelemetry;
171
+ timings: GpuFixedSppFrameTimingTelemetry;
172
+ telemetryMemoryBytes: number;
173
+ signal?: AbortSignal;
174
+ }
123
175
  interface GpuDebugMemorySnapshot {
124
176
  totalTrackedBytes: number;
125
177
  peakTrackedBytes: number;
@@ -256,6 +308,37 @@ interface GpuDebugWavefrontSnapshot {
256
308
  count: number;
257
309
  }[];
258
310
  }
311
+ /** Aggregated fixed-SPP evidence from the session's bounded local history. */
312
+ interface GpuDebugFixedSppSnapshot {
313
+ sampleCount: number;
314
+ measuredRayCountSampleCount: number;
315
+ measuredGpuTimeSampleCount: number;
316
+ totalPrimaryRays: number;
317
+ totalMeasuredSecondaryRays: number;
318
+ totalMeasuredPathSegments: number;
319
+ averagePrimaryRays?: number;
320
+ averageMeasuredSecondaryRays?: number;
321
+ averageMeasuredPathSegments?: number;
322
+ averageGpuTimeMs?: number;
323
+ averageRenderJobTimeMs?: number;
324
+ averageClassificationTimeMs?: number;
325
+ averageCompactionTimeMs?: number;
326
+ averageSamplingTimeMs?: number;
327
+ peakTelemetryMemoryBytes: number;
328
+ byRayCountStatus: readonly {
329
+ status: GpuFixedSppRayCountStatus;
330
+ count: number;
331
+ }[];
332
+ byTimingStatus: readonly {
333
+ status: GpuFixedSppTimingStatus;
334
+ count: number;
335
+ }[];
336
+ byTimestampQueryStatus: readonly {
337
+ status: GpuFixedSppTimestampQueryStatus;
338
+ count: number;
339
+ }[];
340
+ latest?: Readonly<Omit<GpuFixedSppTelemetrySample, "signal">>;
341
+ }
259
342
  interface GpuDebugSnapshot {
260
343
  enabled: boolean;
261
344
  adapter: Readonly<GpuDebugAdapterInfo>;
@@ -266,6 +349,7 @@ interface GpuDebugSnapshot {
266
349
  dag: GpuDebugDagSnapshot;
267
350
  pipeline: GpuDebugPipelineSnapshot;
268
351
  wavefront: GpuDebugWavefrontSnapshot;
352
+ fixedSpp: GpuDebugFixedSppSnapshot;
269
353
  limitations: readonly string[];
270
354
  }
271
355
  interface GpuDebugSession {
@@ -279,6 +363,7 @@ interface GpuDebugSession {
279
363
  recordDependencyUnlock(sample: GpuDependencyUnlockSample): boolean;
280
364
  recordPipelinePhase(sample: GpuPipelinePhaseSample): boolean;
281
365
  recordWavefrontTelemetry(sample: GpuWavefrontTelemetrySample): boolean;
366
+ recordFixedSppTelemetry(sample: GpuFixedSppTelemetrySample): boolean;
282
367
  recordFrame(sample: GpuFrameSample): boolean;
283
368
  getSnapshot(): GpuDebugSnapshot;
284
369
  reset(): void;
@@ -287,9 +372,11 @@ interface GpuDebugSession {
287
372
  declare function estimateDispatchInvocations(sample: GpuDispatchSample): number;
288
373
  declare function createGpuDebugSession(options?: GpuDebugSessionOptions): GpuDebugSession;
289
374
  declare function summarizeWavefrontTelemetry(snapshot: GpuDebugWavefrontSnapshot | undefined): readonly string[];
375
+ /** Formats bounded fixed-SPP ray, timing, and telemetry-memory evidence. */
376
+ declare function summarizeFixedSppTelemetry(snapshot: GpuDebugFixedSppSnapshot | undefined): readonly string[];
290
377
 
291
378
  declare const gpuDebugQueueClasses: readonly ("render" | "simulation" | "lighting" | "post-processing" | "voxel" | "transfer" | "custom")[];
292
379
  declare const gpuResourceCategories: readonly ("custom" | "buffer" | "texture" | "bind-group" | "pipeline")[];
293
380
  declare const gpuPipelinePhases: readonly ("render" | "simulation" | "secondary-simulation" | "scene-preparation")[];
294
381
 
295
- export { type GpuDebugAdapterInfo, type GpuDebugDagSnapshot, type GpuDebugDispatchSnapshot, type GpuDebugFrameSnapshot, type GpuDebugMemorySnapshot, type GpuDebugPipelineSnapshot, type GpuDebugQueueClass, type GpuDebugQueueSnapshot, type GpuDebugSession, type GpuDebugSessionOptions, type GpuDebugSnapshot, type GpuDebugWavefrontSnapshot, type GpuDependencyUnlockSample, type GpuDispatchSample, type GpuFrameSample, type GpuPipelinePhase, type GpuPipelinePhaseSample, type GpuQueueSample, type GpuReadyLaneSample, type GpuResourceCategory, type GpuVector3, type GpuWavefrontHitKindSample, type GpuWavefrontTelemetrySample, type GpuWavefrontTerminationSample, type TrackedGpuAllocation, createGpuDebugSession, estimateDispatchInvocations, gpuDebugQueueClasses, gpuPipelinePhases, gpuResourceCategories, summarizeWavefrontTelemetry };
382
+ export { type GpuDebugAdapterInfo, type GpuDebugDagSnapshot, type GpuDebugDispatchSnapshot, type GpuDebugFixedSppSnapshot, type GpuDebugFrameSnapshot, type GpuDebugMemorySnapshot, type GpuDebugPipelineSnapshot, type GpuDebugQueueClass, type GpuDebugQueueSnapshot, type GpuDebugSession, type GpuDebugSessionOptions, type GpuDebugSnapshot, type GpuDebugWavefrontSnapshot, type GpuDependencyUnlockSample, type GpuDispatchSample, type GpuFixedSppFrameTimingTelemetry, type GpuFixedSppRayCountStatus, type GpuFixedSppRayCountTelemetry, type GpuFixedSppTelemetrySample, type GpuFixedSppTimestampQueryStatus, type GpuFixedSppTimingStatus, type GpuFrameSample, type GpuPipelinePhase, type GpuPipelinePhaseSample, type GpuQueueSample, type GpuReadyLaneSample, type GpuResourceCategory, type GpuVector3, type GpuWavefrontHitKindSample, type GpuWavefrontTelemetrySample, type GpuWavefrontTerminationSample, type TrackedGpuAllocation, createGpuDebugSession, estimateDispatchInvocations, gpuDebugQueueClasses, gpuPipelinePhases, gpuResourceCategories, summarizeFixedSppTelemetry, summarizeWavefrontTelemetry };
package/dist/index.js CHANGED
@@ -139,6 +139,7 @@ var DEFAULT_OPTIONS = Object.freeze({
139
139
  maxRetainedDependencyUnlockSamples: 240,
140
140
  maxRetainedPipelinePhaseSamples: 240,
141
141
  maxRetainedWavefrontSamples: 240,
142
+ maxRetainedFixedSppSamples: 240,
142
143
  maxRetainedFrameSamples: 240,
143
144
  maxTrackedAllocations: 512
144
145
  });
@@ -148,7 +149,32 @@ var LIMITATIONS = Object.freeze([
148
149
  "Hardware hints are optional caller-supplied metadata and may be platform-specific.",
149
150
  "Ready-lane and dependency-unlock diagnostics are caller-reported integration samples, not automatic WebGPU counters.",
150
151
  "Pipeline phase and snapshot-lag diagnostics are caller-reported integration samples, not automatic WebGPU counters.",
151
- "Wavefront queue, hit-buffer, and termination diagnostics are caller-reported summaries rather than full GPU buffer dumps."
152
+ "Wavefront queue, hit-buffer, and termination diagnostics are caller-reported summaries rather than full GPU buffer dumps.",
153
+ "Fixed-SPP ray and timing evidence is retained from caller-resolved renderer statistics; this package does not initiate GPU readbacks."
154
+ ]);
155
+ var FIXED_SPP_RAY_COUNT_STATUSES = Object.freeze([
156
+ "not-requested",
157
+ "available",
158
+ "unavailable",
159
+ "failed"
160
+ ]);
161
+ var FIXED_SPP_TIMING_STATUSES = Object.freeze([
162
+ "not-requested",
163
+ "available",
164
+ "fallback",
165
+ "unavailable",
166
+ "failed"
167
+ ]);
168
+ var FIXED_SPP_TIMESTAMP_QUERY_STATUSES = Object.freeze([
169
+ "not-recorded",
170
+ "available",
171
+ "unsupported",
172
+ "failed"
173
+ ]);
174
+ var FIXED_SPP_TIMING_SOURCES = Object.freeze([
175
+ "timestamp-query",
176
+ "queue-completion",
177
+ "cpu-submit"
152
178
  ]);
153
179
  function clampCount(value, fallback) {
154
180
  if (!value || !Number.isFinite(value) || value <= 0) {
@@ -444,6 +470,282 @@ function normalizeWavefrontTelemetrySample(sample) {
444
470
  )
445
471
  };
446
472
  }
473
+ function readNullableNonNegativeInteger(name, value) {
474
+ if (value === null) {
475
+ return null;
476
+ }
477
+ const parsed = readNonNegativeNumber(name, value);
478
+ if (parsed === void 0 || !Number.isInteger(parsed)) {
479
+ throw new Error(`${name} must be null or an integer greater than or equal to zero.`);
480
+ }
481
+ return parsed;
482
+ }
483
+ function readRequiredNonNegativeInteger(name, value) {
484
+ const parsed = readNonNegativeNumber(name, value);
485
+ if (parsed === void 0 || !Number.isInteger(parsed)) {
486
+ throw new Error(`${name} must be an integer greater than or equal to zero.`);
487
+ }
488
+ return parsed;
489
+ }
490
+ function readRequiredPositiveInteger(name, value) {
491
+ const parsed = readPositiveInteger(name, value);
492
+ if (parsed === void 0) {
493
+ throw new Error(`${name} must be an integer greater than zero.`);
494
+ }
495
+ return parsed;
496
+ }
497
+ function readRequiredNonNegativeNumber(name, value) {
498
+ const parsed = readNonNegativeNumber(name, value);
499
+ if (parsed === void 0) {
500
+ throw new Error(`${name} must be a finite number greater than or equal to zero.`);
501
+ }
502
+ return parsed;
503
+ }
504
+ function readNullableNonNegativeNumber(name, value) {
505
+ if (value === null) {
506
+ return null;
507
+ }
508
+ const parsed = readNonNegativeNumber(name, value);
509
+ if (parsed === void 0) {
510
+ throw new Error(`${name} must be null or a finite number greater than or equal to zero.`);
511
+ }
512
+ return parsed;
513
+ }
514
+ function normalizeEvidenceReason(name, value) {
515
+ if (value === null) {
516
+ return null;
517
+ }
518
+ if (typeof value !== "string" || value.trim().length === 0) {
519
+ throw new Error(`${name} must be null or a non-empty string.`);
520
+ }
521
+ return value.trim().slice(0, 240);
522
+ }
523
+ function normalizeFixedSppRayCounts(value) {
524
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
525
+ throw new Error("fixedSpp.rayCounts must be an object.");
526
+ }
527
+ if (!Array.isArray(value.bounceHistogram)) {
528
+ throw new Error("fixedSpp.rayCounts.bounceHistogram must be an array.");
529
+ }
530
+ const status = assertEnumValue(
531
+ "fixedSpp.rayCounts.status",
532
+ value.status,
533
+ FIXED_SPP_RAY_COUNT_STATUSES
534
+ );
535
+ const source = value.source === null ? null : assertEnumValue(
536
+ "fixedSpp.rayCounts.source",
537
+ value.source,
538
+ ["gpu-active-queue-readback"]
539
+ );
540
+ const expectedPrimaryRays = readNullableNonNegativeInteger(
541
+ "fixedSpp.rayCounts.expectedPrimaryRays",
542
+ value.expectedPrimaryRays
543
+ );
544
+ const observedPrimaryRays = readNullableNonNegativeInteger(
545
+ "fixedSpp.rayCounts.observedPrimaryRays",
546
+ value.observedPrimaryRays
547
+ );
548
+ const secondaryRays = readNullableNonNegativeInteger(
549
+ "fixedSpp.rayCounts.secondaryRays",
550
+ value.secondaryRays
551
+ );
552
+ const totalPathSegments = readNullableNonNegativeInteger(
553
+ "fixedSpp.rayCounts.totalPathSegments",
554
+ value.totalPathSegments
555
+ );
556
+ const bounceHistogram = Object.freeze(
557
+ value.bounceHistogram.map(
558
+ (count, index) => readRequiredNonNegativeInteger(
559
+ `fixedSpp.rayCounts.bounceHistogram[${index}]`,
560
+ count
561
+ )
562
+ )
563
+ );
564
+ const capturedRayCounts = readRequiredNonNegativeInteger(
565
+ "fixedSpp.rayCounts.capturedRayCounts",
566
+ value.capturedRayCounts
567
+ );
568
+ const expectedRayCounts = readRequiredNonNegativeInteger(
569
+ "fixedSpp.rayCounts.expectedRayCounts",
570
+ value.expectedRayCounts
571
+ );
572
+ const reason = normalizeEvidenceReason(
573
+ "fixedSpp.rayCounts.reason",
574
+ value.reason
575
+ );
576
+ if (status === "available" && capturedRayCounts === 0) {
577
+ throw new Error(
578
+ "available fixedSpp.rayCounts require at least one captured ray-count record."
579
+ );
580
+ }
581
+ if (status === "available" && capturedRayCounts !== expectedRayCounts) {
582
+ throw new Error(
583
+ "available fixedSpp.rayCounts capturedRayCounts must match expectedRayCounts."
584
+ );
585
+ }
586
+ if (status === "available" && (source === null || expectedPrimaryRays === null || observedPrimaryRays === null || secondaryRays === null || totalPathSegments === null)) {
587
+ throw new Error(
588
+ "available fixedSpp.rayCounts require a source and complete ray measurements."
589
+ );
590
+ }
591
+ if (status === "available" && bounceHistogram.reduce((total, count) => total + count, 0) !== totalPathSegments) {
592
+ throw new Error(
593
+ "available fixedSpp.rayCounts bounce histogram must sum to totalPathSegments."
594
+ );
595
+ }
596
+ return Object.freeze({
597
+ status,
598
+ source,
599
+ expectedPrimaryRays,
600
+ observedPrimaryRays,
601
+ secondaryRays,
602
+ totalPathSegments,
603
+ bounceHistogram,
604
+ capturedRayCounts,
605
+ expectedRayCounts,
606
+ reason
607
+ });
608
+ }
609
+ function normalizeFixedSppTimings(value) {
610
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
611
+ throw new Error("fixedSpp.timings must be an object.");
612
+ }
613
+ const status = assertEnumValue(
614
+ "fixedSpp.timings.status",
615
+ value.status,
616
+ FIXED_SPP_TIMING_STATUSES
617
+ );
618
+ const source = value.source === null ? null : assertEnumValue(
619
+ "fixedSpp.timings.source",
620
+ value.source,
621
+ FIXED_SPP_TIMING_SOURCES
622
+ );
623
+ const timestampQueryStatus = assertEnumValue(
624
+ "fixedSpp.timings.timestampQueryStatus",
625
+ value.timestampQueryStatus,
626
+ FIXED_SPP_TIMESTAMP_QUERY_STATUSES
627
+ );
628
+ const totalGpuTimeMs = readNullableNonNegativeNumber(
629
+ "fixedSpp.timings.totalGpuTimeMs",
630
+ value.totalGpuTimeMs
631
+ );
632
+ const totalRenderJobTimeMs = readRequiredNonNegativeNumber(
633
+ "fixedSpp.timings.totalRenderJobTimeMs",
634
+ value.totalRenderJobTimeMs
635
+ );
636
+ const classificationTimeMs = readNullableNonNegativeNumber(
637
+ "fixedSpp.timings.classificationTimeMs",
638
+ value.classificationTimeMs
639
+ );
640
+ const compactionTimeMs = readNullableNonNegativeNumber(
641
+ "fixedSpp.timings.compactionTimeMs",
642
+ value.compactionTimeMs
643
+ );
644
+ const samplingTimeMs = readNullableNonNegativeNumber(
645
+ "fixedSpp.timings.samplingTimeMs",
646
+ value.samplingTimeMs
647
+ );
648
+ const reason = normalizeEvidenceReason("fixedSpp.timings.reason", value.reason);
649
+ if (timestampQueryStatus === "available" && (status !== "available" || source !== "timestamp-query" || totalGpuTimeMs === null)) {
650
+ throw new Error(
651
+ "available timestamp-query evidence requires available timestamp timing and totalGpuTimeMs."
652
+ );
653
+ }
654
+ return Object.freeze({
655
+ status,
656
+ source,
657
+ timestampQueryStatus,
658
+ totalGpuTimeMs,
659
+ totalRenderJobTimeMs,
660
+ classificationTimeMs,
661
+ compactionTimeMs,
662
+ samplingTimeMs,
663
+ reason
664
+ });
665
+ }
666
+ function normalizeFixedSppTelemetrySample(sample) {
667
+ if (sample.signal !== void 0 && !isAbortSignalLike(sample.signal)) {
668
+ throw new Error("fixedSpp.signal must be an AbortSignal when provided.");
669
+ }
670
+ const samplesPerPixel = readRequiredPositiveInteger(
671
+ "fixedSpp.samplesPerPixel",
672
+ sample.samplesPerPixel
673
+ );
674
+ const renderedSamplesPerPixel = readRequiredPositiveInteger(
675
+ "fixedSpp.renderedSamplesPerPixel",
676
+ sample.renderedSamplesPerPixel
677
+ );
678
+ if (renderedSamplesPerPixel > samplesPerPixel) {
679
+ throw new Error(
680
+ "fixedSpp.renderedSamplesPerPixel cannot exceed fixedSpp.samplesPerPixel."
681
+ );
682
+ }
683
+ const primaryRays = readRequiredNonNegativeInteger(
684
+ "fixedSpp.primaryRays",
685
+ sample.primaryRays
686
+ );
687
+ const secondaryRays = readNullableNonNegativeInteger(
688
+ "fixedSpp.secondaryRays",
689
+ sample.secondaryRays
690
+ );
691
+ const totalPathSegments = readNullableNonNegativeInteger(
692
+ "fixedSpp.totalPathSegments",
693
+ sample.totalPathSegments
694
+ );
695
+ const rayCounts = normalizeFixedSppRayCounts(sample.rayCounts);
696
+ const timings = normalizeFixedSppTimings(sample.timings);
697
+ const telemetryMemoryBytes = readRequiredNonNegativeInteger(
698
+ "fixedSpp.telemetryMemoryBytes",
699
+ sample.telemetryMemoryBytes
700
+ );
701
+ if (secondaryRays !== rayCounts.secondaryRays) {
702
+ throw new Error(
703
+ "fixedSpp.secondaryRays must match fixedSpp.rayCounts.secondaryRays."
704
+ );
705
+ }
706
+ if (totalPathSegments !== rayCounts.totalPathSegments) {
707
+ throw new Error(
708
+ "fixedSpp.totalPathSegments must match fixedSpp.rayCounts.totalPathSegments."
709
+ );
710
+ }
711
+ if (secondaryRays === null !== (totalPathSegments === null)) {
712
+ throw new Error(
713
+ "fixedSpp.secondaryRays and fixedSpp.totalPathSegments must both be measured or both be null."
714
+ );
715
+ }
716
+ if (secondaryRays !== null && totalPathSegments !== primaryRays + secondaryRays) {
717
+ throw new Error(
718
+ "fixedSpp.totalPathSegments must equal primaryRays plus secondaryRays when measured."
719
+ );
720
+ }
721
+ if (rayCounts.expectedPrimaryRays !== null && rayCounts.expectedPrimaryRays !== primaryRays) {
722
+ throw new Error(
723
+ "fixedSpp.primaryRays must match fixedSpp.rayCounts.expectedPrimaryRays."
724
+ );
725
+ }
726
+ if (rayCounts.status === "available" && rayCounts.observedPrimaryRays !== primaryRays) {
727
+ throw new Error(
728
+ "available fixedSpp.rayCounts observedPrimaryRays must match primaryRays."
729
+ );
730
+ }
731
+ return Object.freeze({
732
+ owner: assertIdentifier("fixedSpp.owner", sample.owner),
733
+ queueClass: assertEnumValue(
734
+ "fixedSpp.queueClass",
735
+ sample.queueClass,
736
+ gpuDebugQueueClasses
737
+ ),
738
+ frameId: sample.frameId === void 0 ? void 0 : assertIdentifier("fixedSpp.frameId", sample.frameId),
739
+ samplesPerPixel,
740
+ renderedSamplesPerPixel,
741
+ primaryRays,
742
+ secondaryRays,
743
+ totalPathSegments,
744
+ rayCounts,
745
+ timings,
746
+ telemetryMemoryBytes
747
+ });
748
+ }
447
749
  function estimateDispatchInvocations(sample) {
448
750
  const normalized = normalizeDispatchSample(sample);
449
751
  return normalized.workgroups.x * normalized.workgroups.y * normalized.workgroups.z * normalized.workgroupSize.x * normalized.workgroupSize.y * normalized.workgroupSize.z;
@@ -475,6 +777,10 @@ function createGpuDebugSession(options = {}) {
475
777
  options.maxRetainedWavefrontSamples,
476
778
  DEFAULT_OPTIONS.maxRetainedWavefrontSamples
477
779
  ),
780
+ maxRetainedFixedSppSamples: clampCount(
781
+ options.maxRetainedFixedSppSamples,
782
+ DEFAULT_OPTIONS.maxRetainedFixedSppSamples
783
+ ),
478
784
  maxRetainedFrameSamples: clampCount(
479
785
  options.maxRetainedFrameSamples,
480
786
  DEFAULT_OPTIONS.maxRetainedFrameSamples
@@ -494,6 +800,7 @@ function createGpuDebugSession(options = {}) {
494
800
  const dependencyUnlockSamples = [];
495
801
  const pipelinePhaseSamples = [];
496
802
  const wavefrontSamples = [];
803
+ const fixedSppSamples = [];
497
804
  const frameSamples = [];
498
805
  let peakTrackedBytes = 0;
499
806
  const totalTrackedBytes = () => [...allocations.values()].reduce((total, allocation) => total + allocation.sizeBytes, 0);
@@ -772,6 +1079,67 @@ function createGpuDebugSession(options = {}) {
772
1079
  byHitKind: [...byHitKind.entries()].map(([kind, count]) => ({ kind, count })).sort((left, right) => right.count - left.count)
773
1080
  };
774
1081
  };
1082
+ const buildFixedSppSnapshot = () => {
1083
+ const primaryRays = fixedSppSamples.map((sample) => sample.primaryRays);
1084
+ const measuredSecondaryRays = fixedSppSamples.map((sample) => sample.secondaryRays).filter((value) => value !== null);
1085
+ const measuredPathSegments = fixedSppSamples.map((sample) => sample.totalPathSegments).filter((value) => value !== null);
1086
+ const gpuTimes = fixedSppSamples.map((sample) => sample.timings.totalGpuTimeMs).filter((value) => value !== null);
1087
+ const renderJobTimes = fixedSppSamples.map(
1088
+ (sample) => sample.timings.totalRenderJobTimeMs
1089
+ );
1090
+ const classificationTimes = fixedSppSamples.map((sample) => sample.timings.classificationTimeMs).filter((value) => value !== null);
1091
+ const compactionTimes = fixedSppSamples.map((sample) => sample.timings.compactionTimeMs).filter((value) => value !== null);
1092
+ const samplingTimes = fixedSppSamples.map((sample) => sample.timings.samplingTimeMs).filter((value) => value !== null);
1093
+ const telemetryMemory = fixedSppSamples.map(
1094
+ (sample) => sample.telemetryMemoryBytes
1095
+ );
1096
+ const byRayCountStatus = /* @__PURE__ */ new Map();
1097
+ const byTimingStatus = /* @__PURE__ */ new Map();
1098
+ const byTimestampQueryStatus = /* @__PURE__ */ new Map();
1099
+ for (const sample of fixedSppSamples) {
1100
+ pushAggregate(byRayCountStatus, sample.rayCounts.status, 1);
1101
+ pushAggregate(byTimingStatus, sample.timings.status, 1);
1102
+ pushAggregate(
1103
+ byTimestampQueryStatus,
1104
+ sample.timings.timestampQueryStatus,
1105
+ 1
1106
+ );
1107
+ }
1108
+ return {
1109
+ sampleCount: fixedSppSamples.length,
1110
+ measuredRayCountSampleCount: measuredPathSegments.length,
1111
+ measuredGpuTimeSampleCount: gpuTimes.length,
1112
+ totalPrimaryRays: primaryRays.reduce((total, value) => total + value, 0),
1113
+ totalMeasuredSecondaryRays: measuredSecondaryRays.reduce(
1114
+ (total, value) => total + value,
1115
+ 0
1116
+ ),
1117
+ totalMeasuredPathSegments: measuredPathSegments.reduce(
1118
+ (total, value) => total + value,
1119
+ 0
1120
+ ),
1121
+ averagePrimaryRays: average(primaryRays),
1122
+ averageMeasuredSecondaryRays: average(measuredSecondaryRays),
1123
+ averageMeasuredPathSegments: average(measuredPathSegments),
1124
+ averageGpuTimeMs: average(gpuTimes),
1125
+ averageRenderJobTimeMs: average(renderJobTimes),
1126
+ averageClassificationTimeMs: average(classificationTimes),
1127
+ averageCompactionTimeMs: average(compactionTimes),
1128
+ averageSamplingTimeMs: average(samplingTimes),
1129
+ peakTelemetryMemoryBytes: telemetryMemory.length > 0 ? Math.max(...telemetryMemory) : 0,
1130
+ byRayCountStatus: [...byRayCountStatus.entries()].map(
1131
+ ([status, count]) => ({ status, count })
1132
+ ),
1133
+ byTimingStatus: [...byTimingStatus.entries()].map(([status, count]) => ({
1134
+ status,
1135
+ count
1136
+ })),
1137
+ byTimestampQueryStatus: [...byTimestampQueryStatus.entries()].map(
1138
+ ([status, count]) => ({ status, count })
1139
+ ),
1140
+ latest: fixedSppSamples[fixedSppSamples.length - 1]
1141
+ };
1142
+ };
775
1143
  return {
776
1144
  isEnabled() {
777
1145
  return enabled;
@@ -861,6 +1229,14 @@ function createGpuDebugSession(options = {}) {
861
1229
  trimHistory(wavefrontSamples, settings.maxRetainedWavefrontSamples);
862
1230
  return true;
863
1231
  },
1232
+ recordFixedSppTelemetry(sample) {
1233
+ if (!enabled || sample.signal?.aborted === true) {
1234
+ return false;
1235
+ }
1236
+ fixedSppSamples.push(normalizeFixedSppTelemetrySample(sample));
1237
+ trimHistory(fixedSppSamples, settings.maxRetainedFixedSppSamples);
1238
+ return true;
1239
+ },
864
1240
  recordFrame(sample) {
865
1241
  if (!enabled || sample.signal?.aborted === true) {
866
1242
  return false;
@@ -904,6 +1280,7 @@ function createGpuDebugSession(options = {}) {
904
1280
  dag: buildDagSnapshot(),
905
1281
  pipeline: buildPipelineSnapshot(),
906
1282
  wavefront: buildWavefrontSnapshot(),
1283
+ fixedSpp: buildFixedSppSnapshot(),
907
1284
  limitations: LIMITATIONS
908
1285
  };
909
1286
  return snapshot;
@@ -917,6 +1294,7 @@ function createGpuDebugSession(options = {}) {
917
1294
  dependencyUnlockSamples.splice(0, dependencyUnlockSamples.length);
918
1295
  pipelinePhaseSamples.splice(0, pipelinePhaseSamples.length);
919
1296
  wavefrontSamples.splice(0, wavefrontSamples.length);
1297
+ fixedSppSamples.splice(0, fixedSppSamples.length);
920
1298
  frameSamples.splice(0, frameSamples.length);
921
1299
  peakTrackedBytes = 0;
922
1300
  }
@@ -950,12 +1328,31 @@ function summarizeWavefrontTelemetry(snapshot) {
950
1328
  );
951
1329
  return Object.freeze(lines);
952
1330
  }
1331
+ function summarizeStatusCounts(entries) {
1332
+ return entries.length === 0 ? "none" : entries.map((entry) => `${entry.status}=${entry.count}`).join(", ");
1333
+ }
1334
+ function sampleLabel(count) {
1335
+ return count === 1 ? "sample" : "samples";
1336
+ }
1337
+ function summarizeFixedSppTelemetry(snapshot) {
1338
+ if (!snapshot || snapshot.sampleCount === 0) {
1339
+ return Object.freeze(["Fixed-SPP telemetry: no samples recorded."]);
1340
+ }
1341
+ const gpuTiming = snapshot.averageGpuTimeMs === void 0 ? "GPU unavailable from 0 samples" : `GPU avg ${snapshot.averageGpuTimeMs.toFixed(2)} ms from ${snapshot.measuredGpuTimeSampleCount} ${sampleLabel(snapshot.measuredGpuTimeSampleCount)}`;
1342
+ const renderJobTiming = snapshot.averageRenderJobTimeMs === void 0 ? "render-job unavailable from 0 samples" : `render-job avg ${snapshot.averageRenderJobTimeMs.toFixed(2)} ms from ${snapshot.sampleCount} ${sampleLabel(snapshot.sampleCount)}`;
1343
+ return Object.freeze([
1344
+ `Fixed-SPP telemetry: ${snapshot.sampleCount} ${sampleLabel(snapshot.sampleCount)}, ${snapshot.totalPrimaryRays} primary rays, ${snapshot.totalMeasuredSecondaryRays} measured secondary rays, ${snapshot.totalMeasuredPathSegments} measured path segments.`,
1345
+ `Timing: ${gpuTiming}; ${renderJobTiming}.`,
1346
+ `Evidence: ray counts ${summarizeStatusCounts(snapshot.byRayCountStatus)}; timestamp queries ${summarizeStatusCounts(snapshot.byTimestampQueryStatus)}; peak telemetry memory ${snapshot.peakTelemetryMemoryBytes} bytes.`
1347
+ ]);
1348
+ }
953
1349
  export {
954
1350
  createGpuDebugSession,
955
1351
  estimateDispatchInvocations,
956
1352
  gpuDebugQueueClasses,
957
1353
  gpuPipelinePhases,
958
1354
  gpuResourceCategories,
1355
+ summarizeFixedSppTelemetry,
959
1356
  summarizeWavefrontTelemetry
960
1357
  };
961
1358
  //# sourceMappingURL=index.js.map