@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/CHANGELOG.md CHANGED
@@ -20,6 +20,40 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
20
20
  - **Security**
21
21
  - (placeholder)
22
22
 
23
+ ## [0.2.7] - 2026-08-31
24
+
25
+ - **Added**
26
+ - (placeholder)
27
+
28
+ - **Changed**
29
+ - (placeholder)
30
+
31
+ - **Fixed**
32
+ - Fixed fixed-SPP telemetry admission so exact tile/sample/depth readback
33
+ record counts are preserved independently from the collapsed per-bounce
34
+ histogram while mismatched expected/captured records still fail closed.
35
+ - (placeholder)
36
+
37
+ - **Security**
38
+ - (placeholder)
39
+
40
+ ## [0.2.6] - 2026-08-31
41
+
42
+ - **Added**
43
+ - Added bounded fixed-SPP renderer telemetry ingestion and summaries for ray
44
+ counts, path segments, timing evidence, timestamp-query status, and telemetry
45
+ memory without initiating GPU readbacks.
46
+ - Added `summarizeFixedSppTelemetry(...)` for compact operator evidence.
47
+
48
+ - **Changed**
49
+ - (placeholder)
50
+
51
+ - **Fixed**
52
+ - (placeholder)
53
+
54
+ - **Security**
55
+ - (placeholder)
56
+
23
57
  ## [0.2.5] - 2026-08-30
24
58
 
25
59
  - **Added**
@@ -253,3 +287,5 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
253
287
  [0.2.3]: https://github.com/Plasius-LTD/gpu-debug/releases/tag/v0.2.3
254
288
  [0.2.4]: https://github.com/Plasius-LTD/gpu-debug/releases/tag/v0.2.4
255
289
  [0.2.5]: https://github.com/Plasius-LTD/gpu-debug/releases/tag/v0.2.5
290
+ [0.2.6]: https://github.com/Plasius-LTD/gpu-debug/releases/tag/v0.2.6
291
+ [0.2.7]: https://github.com/Plasius-LTD/gpu-debug/releases/tag/v0.2.7
package/README.md CHANGED
@@ -41,6 +41,8 @@ scene from the public `@plasius/gpu-shared` package surface, while
41
41
  supply those samples.
42
42
  - Records compact wavefront queue, hit-buffer, and termination summaries
43
43
  without dumping raw GPU buffers.
44
+ - Retains bounded fixed-SPP renderer evidence for primary/secondary rays, path
45
+ segments, GPU/render-job timing, timestamp-query status, and telemetry memory.
44
46
  - Summarizes frame-budget pressure alongside dispatch activity.
45
47
  - Accepts optional host-supplied hardware hints such as memory capacity or core
46
48
  count when a native or privileged runtime can provide them.
@@ -56,6 +58,7 @@ import {
56
58
  gpuDebugQueueClasses,
57
59
  gpuPipelinePhases,
58
60
  gpuResourceCategories,
61
+ summarizeFixedSppTelemetry,
59
62
  summarizeWavefrontTelemetry,
60
63
  } from "@plasius/gpu-debug";
61
64
 
@@ -156,9 +159,26 @@ debug.recordWavefrontTelemetry({
156
159
  ],
157
160
  });
158
161
 
162
+ // Pass statistics already resolved by @plasius/gpu-renderer. This call never
163
+ // initiates a GPU readback or enables renderer diagnostics on its own.
164
+ debug.recordFixedSppTelemetry({
165
+ owner: "wavefront",
166
+ queueClass: "render",
167
+ frameId: "frame-101",
168
+ samplesPerPixel: rendererStats.samplesPerPixel,
169
+ renderedSamplesPerPixel: rendererStats.renderedSamplesPerPixel,
170
+ primaryRays: rendererStats.primaryRays,
171
+ secondaryRays: rendererStats.secondaryRays,
172
+ totalPathSegments: rendererStats.totalPathSegments,
173
+ rayCounts: rendererStats.rayCounts,
174
+ timings: rendererStats.timings,
175
+ telemetryMemoryBytes: rendererStats.telemetryMemoryBytes,
176
+ });
177
+
159
178
  const snapshot = debug.getSnapshot();
160
179
  console.log(snapshot);
161
180
  console.log(summarizeWavefrontTelemetry(snapshot.wavefront));
181
+ console.log(summarizeFixedSppTelemetry(snapshot.fixedSpp));
162
182
  releaseParticles();
163
183
  ```
164
184
 
@@ -179,6 +199,8 @@ Portable WebGPU does not currently guarantee authoritative access to:
179
199
  - pipeline phase and snapshot-lag summaries when integrations report them,
180
200
  - wavefront queue, hit-buffer, termination, and bounce-depth summaries when
181
201
  integrations report compact telemetry,
202
+ - fixed-SPP ray, path-segment, timing, timestamp-query, and telemetry-memory
203
+ evidence when renderer integrations report already-resolved frame statistics,
182
204
  - optional hardware hints provided by the host runtime.
183
205
 
184
206
  If a native shell, browser extension, or proprietary platform layer can provide
@@ -189,6 +211,7 @@ an inferred optimization aid rather than a full hardware profiler.
189
211
 
190
212
  - `createGpuDebugSession(options?)`
191
213
  - `estimateDispatchInvocations(sample)`
214
+ - `summarizeFixedSppTelemetry(snapshot.fixedSpp)`
192
215
  - `gpuDebugQueueClasses`
193
216
  - `gpuPipelinePhases`
194
217
  - `gpuResourceCategories`
@@ -198,6 +221,19 @@ The exported constants are the docs-first enum contract for integrations that
198
221
  need to validate or surface queue classes, pipeline phases, or tracked resource
199
222
  categories without importing internal validation helpers.
200
223
 
224
+ `recordFixedSppTelemetry(sample)` accepts the fixed-SPP subset of the canonical
225
+ renderer frame statistics structurally, so `gpu-debug` does not need a runtime
226
+ dependency on the renderer. The method is a local ingestion boundary only: it
227
+ does not call a renderer, map a buffer, request timestamps, or read GPU memory.
228
+ Nullable secondary-ray, path-segment, and GPU-time values remain nullable in the
229
+ snapshot, while aggregates explicitly identify how many samples were measured.
230
+ GPU counter record cardinality is validated independently from the collapsed
231
+ bounce histogram: available evidence requires a positive
232
+ `capturedRayCounts === expectedRayCounts`, while histogram buckets must sum to
233
+ `totalPathSegments`. A renderer can therefore report many tile/sample/depth
234
+ records collapsed into a smaller per-bounce histogram without losing the exact
235
+ readback count.
236
+
201
237
  ## Worker and Frame Correlation
202
238
 
203
239
  When worker-based packages use `@plasius/gpu-worker`, prefer passing stable
package/dist/index.cjs CHANGED
@@ -25,6 +25,7 @@ __export(index_exports, {
25
25
  gpuDebugQueueClasses: () => gpuDebugQueueClasses,
26
26
  gpuPipelinePhases: () => gpuPipelinePhases,
27
27
  gpuResourceCategories: () => gpuResourceCategories,
28
+ summarizeFixedSppTelemetry: () => summarizeFixedSppTelemetry,
28
29
  summarizeWavefrontTelemetry: () => summarizeWavefrontTelemetry
29
30
  });
30
31
  module.exports = __toCommonJS(index_exports);
@@ -170,6 +171,7 @@ var DEFAULT_OPTIONS = Object.freeze({
170
171
  maxRetainedDependencyUnlockSamples: 240,
171
172
  maxRetainedPipelinePhaseSamples: 240,
172
173
  maxRetainedWavefrontSamples: 240,
174
+ maxRetainedFixedSppSamples: 240,
173
175
  maxRetainedFrameSamples: 240,
174
176
  maxTrackedAllocations: 512
175
177
  });
@@ -179,7 +181,32 @@ var LIMITATIONS = Object.freeze([
179
181
  "Hardware hints are optional caller-supplied metadata and may be platform-specific.",
180
182
  "Ready-lane and dependency-unlock diagnostics are caller-reported integration samples, not automatic WebGPU counters.",
181
183
  "Pipeline phase and snapshot-lag diagnostics are caller-reported integration samples, not automatic WebGPU counters.",
182
- "Wavefront queue, hit-buffer, and termination diagnostics are caller-reported summaries rather than full GPU buffer dumps."
184
+ "Wavefront queue, hit-buffer, and termination diagnostics are caller-reported summaries rather than full GPU buffer dumps.",
185
+ "Fixed-SPP ray and timing evidence is retained from caller-resolved renderer statistics; this package does not initiate GPU readbacks."
186
+ ]);
187
+ var FIXED_SPP_RAY_COUNT_STATUSES = Object.freeze([
188
+ "not-requested",
189
+ "available",
190
+ "unavailable",
191
+ "failed"
192
+ ]);
193
+ var FIXED_SPP_TIMING_STATUSES = Object.freeze([
194
+ "not-requested",
195
+ "available",
196
+ "fallback",
197
+ "unavailable",
198
+ "failed"
199
+ ]);
200
+ var FIXED_SPP_TIMESTAMP_QUERY_STATUSES = Object.freeze([
201
+ "not-recorded",
202
+ "available",
203
+ "unsupported",
204
+ "failed"
205
+ ]);
206
+ var FIXED_SPP_TIMING_SOURCES = Object.freeze([
207
+ "timestamp-query",
208
+ "queue-completion",
209
+ "cpu-submit"
183
210
  ]);
184
211
  function clampCount(value, fallback) {
185
212
  if (!value || !Number.isFinite(value) || value <= 0) {
@@ -475,6 +502,282 @@ function normalizeWavefrontTelemetrySample(sample) {
475
502
  )
476
503
  };
477
504
  }
505
+ function readNullableNonNegativeInteger(name, value) {
506
+ if (value === null) {
507
+ return null;
508
+ }
509
+ const parsed = readNonNegativeNumber(name, value);
510
+ if (parsed === void 0 || !Number.isInteger(parsed)) {
511
+ throw new Error(`${name} must be null or an integer greater than or equal to zero.`);
512
+ }
513
+ return parsed;
514
+ }
515
+ function readRequiredNonNegativeInteger(name, value) {
516
+ const parsed = readNonNegativeNumber(name, value);
517
+ if (parsed === void 0 || !Number.isInteger(parsed)) {
518
+ throw new Error(`${name} must be an integer greater than or equal to zero.`);
519
+ }
520
+ return parsed;
521
+ }
522
+ function readRequiredPositiveInteger(name, value) {
523
+ const parsed = readPositiveInteger(name, value);
524
+ if (parsed === void 0) {
525
+ throw new Error(`${name} must be an integer greater than zero.`);
526
+ }
527
+ return parsed;
528
+ }
529
+ function readRequiredNonNegativeNumber(name, value) {
530
+ const parsed = readNonNegativeNumber(name, value);
531
+ if (parsed === void 0) {
532
+ throw new Error(`${name} must be a finite number greater than or equal to zero.`);
533
+ }
534
+ return parsed;
535
+ }
536
+ function readNullableNonNegativeNumber(name, value) {
537
+ if (value === null) {
538
+ return null;
539
+ }
540
+ const parsed = readNonNegativeNumber(name, value);
541
+ if (parsed === void 0) {
542
+ throw new Error(`${name} must be null or a finite number greater than or equal to zero.`);
543
+ }
544
+ return parsed;
545
+ }
546
+ function normalizeEvidenceReason(name, value) {
547
+ if (value === null) {
548
+ return null;
549
+ }
550
+ if (typeof value !== "string" || value.trim().length === 0) {
551
+ throw new Error(`${name} must be null or a non-empty string.`);
552
+ }
553
+ return value.trim().slice(0, 240);
554
+ }
555
+ function normalizeFixedSppRayCounts(value) {
556
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
557
+ throw new Error("fixedSpp.rayCounts must be an object.");
558
+ }
559
+ if (!Array.isArray(value.bounceHistogram)) {
560
+ throw new Error("fixedSpp.rayCounts.bounceHistogram must be an array.");
561
+ }
562
+ const status = assertEnumValue(
563
+ "fixedSpp.rayCounts.status",
564
+ value.status,
565
+ FIXED_SPP_RAY_COUNT_STATUSES
566
+ );
567
+ const source = value.source === null ? null : assertEnumValue(
568
+ "fixedSpp.rayCounts.source",
569
+ value.source,
570
+ ["gpu-active-queue-readback"]
571
+ );
572
+ const expectedPrimaryRays = readNullableNonNegativeInteger(
573
+ "fixedSpp.rayCounts.expectedPrimaryRays",
574
+ value.expectedPrimaryRays
575
+ );
576
+ const observedPrimaryRays = readNullableNonNegativeInteger(
577
+ "fixedSpp.rayCounts.observedPrimaryRays",
578
+ value.observedPrimaryRays
579
+ );
580
+ const secondaryRays = readNullableNonNegativeInteger(
581
+ "fixedSpp.rayCounts.secondaryRays",
582
+ value.secondaryRays
583
+ );
584
+ const totalPathSegments = readNullableNonNegativeInteger(
585
+ "fixedSpp.rayCounts.totalPathSegments",
586
+ value.totalPathSegments
587
+ );
588
+ const bounceHistogram = Object.freeze(
589
+ value.bounceHistogram.map(
590
+ (count, index) => readRequiredNonNegativeInteger(
591
+ `fixedSpp.rayCounts.bounceHistogram[${index}]`,
592
+ count
593
+ )
594
+ )
595
+ );
596
+ const capturedRayCounts = readRequiredNonNegativeInteger(
597
+ "fixedSpp.rayCounts.capturedRayCounts",
598
+ value.capturedRayCounts
599
+ );
600
+ const expectedRayCounts = readRequiredNonNegativeInteger(
601
+ "fixedSpp.rayCounts.expectedRayCounts",
602
+ value.expectedRayCounts
603
+ );
604
+ const reason = normalizeEvidenceReason(
605
+ "fixedSpp.rayCounts.reason",
606
+ value.reason
607
+ );
608
+ if (status === "available" && capturedRayCounts === 0) {
609
+ throw new Error(
610
+ "available fixedSpp.rayCounts require at least one captured ray-count record."
611
+ );
612
+ }
613
+ if (status === "available" && capturedRayCounts !== expectedRayCounts) {
614
+ throw new Error(
615
+ "available fixedSpp.rayCounts capturedRayCounts must match expectedRayCounts."
616
+ );
617
+ }
618
+ if (status === "available" && (source === null || expectedPrimaryRays === null || observedPrimaryRays === null || secondaryRays === null || totalPathSegments === null)) {
619
+ throw new Error(
620
+ "available fixedSpp.rayCounts require a source and complete ray measurements."
621
+ );
622
+ }
623
+ if (status === "available" && bounceHistogram.reduce((total, count) => total + count, 0) !== totalPathSegments) {
624
+ throw new Error(
625
+ "available fixedSpp.rayCounts bounce histogram must sum to totalPathSegments."
626
+ );
627
+ }
628
+ return Object.freeze({
629
+ status,
630
+ source,
631
+ expectedPrimaryRays,
632
+ observedPrimaryRays,
633
+ secondaryRays,
634
+ totalPathSegments,
635
+ bounceHistogram,
636
+ capturedRayCounts,
637
+ expectedRayCounts,
638
+ reason
639
+ });
640
+ }
641
+ function normalizeFixedSppTimings(value) {
642
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
643
+ throw new Error("fixedSpp.timings must be an object.");
644
+ }
645
+ const status = assertEnumValue(
646
+ "fixedSpp.timings.status",
647
+ value.status,
648
+ FIXED_SPP_TIMING_STATUSES
649
+ );
650
+ const source = value.source === null ? null : assertEnumValue(
651
+ "fixedSpp.timings.source",
652
+ value.source,
653
+ FIXED_SPP_TIMING_SOURCES
654
+ );
655
+ const timestampQueryStatus = assertEnumValue(
656
+ "fixedSpp.timings.timestampQueryStatus",
657
+ value.timestampQueryStatus,
658
+ FIXED_SPP_TIMESTAMP_QUERY_STATUSES
659
+ );
660
+ const totalGpuTimeMs = readNullableNonNegativeNumber(
661
+ "fixedSpp.timings.totalGpuTimeMs",
662
+ value.totalGpuTimeMs
663
+ );
664
+ const totalRenderJobTimeMs = readRequiredNonNegativeNumber(
665
+ "fixedSpp.timings.totalRenderJobTimeMs",
666
+ value.totalRenderJobTimeMs
667
+ );
668
+ const classificationTimeMs = readNullableNonNegativeNumber(
669
+ "fixedSpp.timings.classificationTimeMs",
670
+ value.classificationTimeMs
671
+ );
672
+ const compactionTimeMs = readNullableNonNegativeNumber(
673
+ "fixedSpp.timings.compactionTimeMs",
674
+ value.compactionTimeMs
675
+ );
676
+ const samplingTimeMs = readNullableNonNegativeNumber(
677
+ "fixedSpp.timings.samplingTimeMs",
678
+ value.samplingTimeMs
679
+ );
680
+ const reason = normalizeEvidenceReason("fixedSpp.timings.reason", value.reason);
681
+ if (timestampQueryStatus === "available" && (status !== "available" || source !== "timestamp-query" || totalGpuTimeMs === null)) {
682
+ throw new Error(
683
+ "available timestamp-query evidence requires available timestamp timing and totalGpuTimeMs."
684
+ );
685
+ }
686
+ return Object.freeze({
687
+ status,
688
+ source,
689
+ timestampQueryStatus,
690
+ totalGpuTimeMs,
691
+ totalRenderJobTimeMs,
692
+ classificationTimeMs,
693
+ compactionTimeMs,
694
+ samplingTimeMs,
695
+ reason
696
+ });
697
+ }
698
+ function normalizeFixedSppTelemetrySample(sample) {
699
+ if (sample.signal !== void 0 && !isAbortSignalLike(sample.signal)) {
700
+ throw new Error("fixedSpp.signal must be an AbortSignal when provided.");
701
+ }
702
+ const samplesPerPixel = readRequiredPositiveInteger(
703
+ "fixedSpp.samplesPerPixel",
704
+ sample.samplesPerPixel
705
+ );
706
+ const renderedSamplesPerPixel = readRequiredPositiveInteger(
707
+ "fixedSpp.renderedSamplesPerPixel",
708
+ sample.renderedSamplesPerPixel
709
+ );
710
+ if (renderedSamplesPerPixel > samplesPerPixel) {
711
+ throw new Error(
712
+ "fixedSpp.renderedSamplesPerPixel cannot exceed fixedSpp.samplesPerPixel."
713
+ );
714
+ }
715
+ const primaryRays = readRequiredNonNegativeInteger(
716
+ "fixedSpp.primaryRays",
717
+ sample.primaryRays
718
+ );
719
+ const secondaryRays = readNullableNonNegativeInteger(
720
+ "fixedSpp.secondaryRays",
721
+ sample.secondaryRays
722
+ );
723
+ const totalPathSegments = readNullableNonNegativeInteger(
724
+ "fixedSpp.totalPathSegments",
725
+ sample.totalPathSegments
726
+ );
727
+ const rayCounts = normalizeFixedSppRayCounts(sample.rayCounts);
728
+ const timings = normalizeFixedSppTimings(sample.timings);
729
+ const telemetryMemoryBytes = readRequiredNonNegativeInteger(
730
+ "fixedSpp.telemetryMemoryBytes",
731
+ sample.telemetryMemoryBytes
732
+ );
733
+ if (secondaryRays !== rayCounts.secondaryRays) {
734
+ throw new Error(
735
+ "fixedSpp.secondaryRays must match fixedSpp.rayCounts.secondaryRays."
736
+ );
737
+ }
738
+ if (totalPathSegments !== rayCounts.totalPathSegments) {
739
+ throw new Error(
740
+ "fixedSpp.totalPathSegments must match fixedSpp.rayCounts.totalPathSegments."
741
+ );
742
+ }
743
+ if (secondaryRays === null !== (totalPathSegments === null)) {
744
+ throw new Error(
745
+ "fixedSpp.secondaryRays and fixedSpp.totalPathSegments must both be measured or both be null."
746
+ );
747
+ }
748
+ if (secondaryRays !== null && totalPathSegments !== primaryRays + secondaryRays) {
749
+ throw new Error(
750
+ "fixedSpp.totalPathSegments must equal primaryRays plus secondaryRays when measured."
751
+ );
752
+ }
753
+ if (rayCounts.expectedPrimaryRays !== null && rayCounts.expectedPrimaryRays !== primaryRays) {
754
+ throw new Error(
755
+ "fixedSpp.primaryRays must match fixedSpp.rayCounts.expectedPrimaryRays."
756
+ );
757
+ }
758
+ if (rayCounts.status === "available" && rayCounts.observedPrimaryRays !== primaryRays) {
759
+ throw new Error(
760
+ "available fixedSpp.rayCounts observedPrimaryRays must match primaryRays."
761
+ );
762
+ }
763
+ return Object.freeze({
764
+ owner: assertIdentifier("fixedSpp.owner", sample.owner),
765
+ queueClass: assertEnumValue(
766
+ "fixedSpp.queueClass",
767
+ sample.queueClass,
768
+ gpuDebugQueueClasses
769
+ ),
770
+ frameId: sample.frameId === void 0 ? void 0 : assertIdentifier("fixedSpp.frameId", sample.frameId),
771
+ samplesPerPixel,
772
+ renderedSamplesPerPixel,
773
+ primaryRays,
774
+ secondaryRays,
775
+ totalPathSegments,
776
+ rayCounts,
777
+ timings,
778
+ telemetryMemoryBytes
779
+ });
780
+ }
478
781
  function estimateDispatchInvocations(sample) {
479
782
  const normalized = normalizeDispatchSample(sample);
480
783
  return normalized.workgroups.x * normalized.workgroups.y * normalized.workgroups.z * normalized.workgroupSize.x * normalized.workgroupSize.y * normalized.workgroupSize.z;
@@ -506,6 +809,10 @@ function createGpuDebugSession(options = {}) {
506
809
  options.maxRetainedWavefrontSamples,
507
810
  DEFAULT_OPTIONS.maxRetainedWavefrontSamples
508
811
  ),
812
+ maxRetainedFixedSppSamples: clampCount(
813
+ options.maxRetainedFixedSppSamples,
814
+ DEFAULT_OPTIONS.maxRetainedFixedSppSamples
815
+ ),
509
816
  maxRetainedFrameSamples: clampCount(
510
817
  options.maxRetainedFrameSamples,
511
818
  DEFAULT_OPTIONS.maxRetainedFrameSamples
@@ -525,6 +832,7 @@ function createGpuDebugSession(options = {}) {
525
832
  const dependencyUnlockSamples = [];
526
833
  const pipelinePhaseSamples = [];
527
834
  const wavefrontSamples = [];
835
+ const fixedSppSamples = [];
528
836
  const frameSamples = [];
529
837
  let peakTrackedBytes = 0;
530
838
  const totalTrackedBytes = () => [...allocations.values()].reduce((total, allocation) => total + allocation.sizeBytes, 0);
@@ -803,6 +1111,67 @@ function createGpuDebugSession(options = {}) {
803
1111
  byHitKind: [...byHitKind.entries()].map(([kind, count]) => ({ kind, count })).sort((left, right) => right.count - left.count)
804
1112
  };
805
1113
  };
1114
+ const buildFixedSppSnapshot = () => {
1115
+ const primaryRays = fixedSppSamples.map((sample) => sample.primaryRays);
1116
+ const measuredSecondaryRays = fixedSppSamples.map((sample) => sample.secondaryRays).filter((value) => value !== null);
1117
+ const measuredPathSegments = fixedSppSamples.map((sample) => sample.totalPathSegments).filter((value) => value !== null);
1118
+ const gpuTimes = fixedSppSamples.map((sample) => sample.timings.totalGpuTimeMs).filter((value) => value !== null);
1119
+ const renderJobTimes = fixedSppSamples.map(
1120
+ (sample) => sample.timings.totalRenderJobTimeMs
1121
+ );
1122
+ const classificationTimes = fixedSppSamples.map((sample) => sample.timings.classificationTimeMs).filter((value) => value !== null);
1123
+ const compactionTimes = fixedSppSamples.map((sample) => sample.timings.compactionTimeMs).filter((value) => value !== null);
1124
+ const samplingTimes = fixedSppSamples.map((sample) => sample.timings.samplingTimeMs).filter((value) => value !== null);
1125
+ const telemetryMemory = fixedSppSamples.map(
1126
+ (sample) => sample.telemetryMemoryBytes
1127
+ );
1128
+ const byRayCountStatus = /* @__PURE__ */ new Map();
1129
+ const byTimingStatus = /* @__PURE__ */ new Map();
1130
+ const byTimestampQueryStatus = /* @__PURE__ */ new Map();
1131
+ for (const sample of fixedSppSamples) {
1132
+ pushAggregate(byRayCountStatus, sample.rayCounts.status, 1);
1133
+ pushAggregate(byTimingStatus, sample.timings.status, 1);
1134
+ pushAggregate(
1135
+ byTimestampQueryStatus,
1136
+ sample.timings.timestampQueryStatus,
1137
+ 1
1138
+ );
1139
+ }
1140
+ return {
1141
+ sampleCount: fixedSppSamples.length,
1142
+ measuredRayCountSampleCount: measuredPathSegments.length,
1143
+ measuredGpuTimeSampleCount: gpuTimes.length,
1144
+ totalPrimaryRays: primaryRays.reduce((total, value) => total + value, 0),
1145
+ totalMeasuredSecondaryRays: measuredSecondaryRays.reduce(
1146
+ (total, value) => total + value,
1147
+ 0
1148
+ ),
1149
+ totalMeasuredPathSegments: measuredPathSegments.reduce(
1150
+ (total, value) => total + value,
1151
+ 0
1152
+ ),
1153
+ averagePrimaryRays: average(primaryRays),
1154
+ averageMeasuredSecondaryRays: average(measuredSecondaryRays),
1155
+ averageMeasuredPathSegments: average(measuredPathSegments),
1156
+ averageGpuTimeMs: average(gpuTimes),
1157
+ averageRenderJobTimeMs: average(renderJobTimes),
1158
+ averageClassificationTimeMs: average(classificationTimes),
1159
+ averageCompactionTimeMs: average(compactionTimes),
1160
+ averageSamplingTimeMs: average(samplingTimes),
1161
+ peakTelemetryMemoryBytes: telemetryMemory.length > 0 ? Math.max(...telemetryMemory) : 0,
1162
+ byRayCountStatus: [...byRayCountStatus.entries()].map(
1163
+ ([status, count]) => ({ status, count })
1164
+ ),
1165
+ byTimingStatus: [...byTimingStatus.entries()].map(([status, count]) => ({
1166
+ status,
1167
+ count
1168
+ })),
1169
+ byTimestampQueryStatus: [...byTimestampQueryStatus.entries()].map(
1170
+ ([status, count]) => ({ status, count })
1171
+ ),
1172
+ latest: fixedSppSamples[fixedSppSamples.length - 1]
1173
+ };
1174
+ };
806
1175
  return {
807
1176
  isEnabled() {
808
1177
  return enabled;
@@ -892,6 +1261,14 @@ function createGpuDebugSession(options = {}) {
892
1261
  trimHistory(wavefrontSamples, settings.maxRetainedWavefrontSamples);
893
1262
  return true;
894
1263
  },
1264
+ recordFixedSppTelemetry(sample) {
1265
+ if (!enabled || sample.signal?.aborted === true) {
1266
+ return false;
1267
+ }
1268
+ fixedSppSamples.push(normalizeFixedSppTelemetrySample(sample));
1269
+ trimHistory(fixedSppSamples, settings.maxRetainedFixedSppSamples);
1270
+ return true;
1271
+ },
895
1272
  recordFrame(sample) {
896
1273
  if (!enabled || sample.signal?.aborted === true) {
897
1274
  return false;
@@ -935,6 +1312,7 @@ function createGpuDebugSession(options = {}) {
935
1312
  dag: buildDagSnapshot(),
936
1313
  pipeline: buildPipelineSnapshot(),
937
1314
  wavefront: buildWavefrontSnapshot(),
1315
+ fixedSpp: buildFixedSppSnapshot(),
938
1316
  limitations: LIMITATIONS
939
1317
  };
940
1318
  return snapshot;
@@ -948,6 +1326,7 @@ function createGpuDebugSession(options = {}) {
948
1326
  dependencyUnlockSamples.splice(0, dependencyUnlockSamples.length);
949
1327
  pipelinePhaseSamples.splice(0, pipelinePhaseSamples.length);
950
1328
  wavefrontSamples.splice(0, wavefrontSamples.length);
1329
+ fixedSppSamples.splice(0, fixedSppSamples.length);
951
1330
  frameSamples.splice(0, frameSamples.length);
952
1331
  peakTrackedBytes = 0;
953
1332
  }
@@ -981,6 +1360,24 @@ function summarizeWavefrontTelemetry(snapshot) {
981
1360
  );
982
1361
  return Object.freeze(lines);
983
1362
  }
1363
+ function summarizeStatusCounts(entries) {
1364
+ return entries.length === 0 ? "none" : entries.map((entry) => `${entry.status}=${entry.count}`).join(", ");
1365
+ }
1366
+ function sampleLabel(count) {
1367
+ return count === 1 ? "sample" : "samples";
1368
+ }
1369
+ function summarizeFixedSppTelemetry(snapshot) {
1370
+ if (!snapshot || snapshot.sampleCount === 0) {
1371
+ return Object.freeze(["Fixed-SPP telemetry: no samples recorded."]);
1372
+ }
1373
+ const gpuTiming = snapshot.averageGpuTimeMs === void 0 ? "GPU unavailable from 0 samples" : `GPU avg ${snapshot.averageGpuTimeMs.toFixed(2)} ms from ${snapshot.measuredGpuTimeSampleCount} ${sampleLabel(snapshot.measuredGpuTimeSampleCount)}`;
1374
+ 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)}`;
1375
+ return Object.freeze([
1376
+ `Fixed-SPP telemetry: ${snapshot.sampleCount} ${sampleLabel(snapshot.sampleCount)}, ${snapshot.totalPrimaryRays} primary rays, ${snapshot.totalMeasuredSecondaryRays} measured secondary rays, ${snapshot.totalMeasuredPathSegments} measured path segments.`,
1377
+ `Timing: ${gpuTiming}; ${renderJobTiming}.`,
1378
+ `Evidence: ray counts ${summarizeStatusCounts(snapshot.byRayCountStatus)}; timestamp queries ${summarizeStatusCounts(snapshot.byTimestampQueryStatus)}; peak telemetry memory ${snapshot.peakTelemetryMemoryBytes} bytes.`
1379
+ ]);
1380
+ }
984
1381
  // Annotate the CommonJS export names for ESM import in node:
985
1382
  0 && (module.exports = {
986
1383
  createGpuDebugSession,
@@ -988,6 +1385,7 @@ function summarizeWavefrontTelemetry(snapshot) {
988
1385
  gpuDebugQueueClasses,
989
1386
  gpuPipelinePhases,
990
1387
  gpuResourceCategories,
1388
+ summarizeFixedSppTelemetry,
991
1389
  summarizeWavefrontTelemetry
992
1390
  });
993
1391
  //# sourceMappingURL=index.cjs.map