@plasius/gpu-debug 0.2.4 → 0.2.6

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,55 @@ 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
+ readonly capturedRayCounts: number;
140
+ readonly expectedRayCounts: number;
141
+ readonly reason: string | null;
142
+ }
143
+ /** Timing evidence from a fixed-SPP renderer frame. */
144
+ interface GpuFixedSppFrameTimingTelemetry {
145
+ readonly status: GpuFixedSppTimingStatus;
146
+ readonly source: "timestamp-query" | "queue-completion" | "cpu-submit" | null;
147
+ readonly timestampQueryStatus: GpuFixedSppTimestampQueryStatus;
148
+ readonly totalGpuTimeMs: number | null;
149
+ readonly totalRenderJobTimeMs: number;
150
+ readonly classificationTimeMs: number | null;
151
+ readonly compactionTimeMs: number | null;
152
+ readonly samplingTimeMs: number | null;
153
+ readonly reason: string | null;
154
+ }
155
+ /**
156
+ * Caller-reported fixed-SPP frame evidence. Recording this sample never starts a
157
+ * readback; callers pass an already-resolved renderer statistics snapshot.
158
+ */
159
+ interface GpuFixedSppTelemetrySample {
160
+ owner: string;
161
+ queueClass: GpuDebugQueueClass;
162
+ frameId?: string;
163
+ samplesPerPixel: number;
164
+ renderedSamplesPerPixel: number;
165
+ primaryRays: number;
166
+ secondaryRays: number | null;
167
+ totalPathSegments: number | null;
168
+ rayCounts: GpuFixedSppRayCountTelemetry;
169
+ timings: GpuFixedSppFrameTimingTelemetry;
170
+ telemetryMemoryBytes: number;
171
+ signal?: AbortSignal;
172
+ }
123
173
  interface GpuDebugMemorySnapshot {
124
174
  totalTrackedBytes: number;
125
175
  peakTrackedBytes: number;
@@ -256,6 +306,37 @@ interface GpuDebugWavefrontSnapshot {
256
306
  count: number;
257
307
  }[];
258
308
  }
309
+ /** Aggregated fixed-SPP evidence from the session's bounded local history. */
310
+ interface GpuDebugFixedSppSnapshot {
311
+ sampleCount: number;
312
+ measuredRayCountSampleCount: number;
313
+ measuredGpuTimeSampleCount: number;
314
+ totalPrimaryRays: number;
315
+ totalMeasuredSecondaryRays: number;
316
+ totalMeasuredPathSegments: number;
317
+ averagePrimaryRays?: number;
318
+ averageMeasuredSecondaryRays?: number;
319
+ averageMeasuredPathSegments?: number;
320
+ averageGpuTimeMs?: number;
321
+ averageRenderJobTimeMs?: number;
322
+ averageClassificationTimeMs?: number;
323
+ averageCompactionTimeMs?: number;
324
+ averageSamplingTimeMs?: number;
325
+ peakTelemetryMemoryBytes: number;
326
+ byRayCountStatus: readonly {
327
+ status: GpuFixedSppRayCountStatus;
328
+ count: number;
329
+ }[];
330
+ byTimingStatus: readonly {
331
+ status: GpuFixedSppTimingStatus;
332
+ count: number;
333
+ }[];
334
+ byTimestampQueryStatus: readonly {
335
+ status: GpuFixedSppTimestampQueryStatus;
336
+ count: number;
337
+ }[];
338
+ latest?: Readonly<Omit<GpuFixedSppTelemetrySample, "signal">>;
339
+ }
259
340
  interface GpuDebugSnapshot {
260
341
  enabled: boolean;
261
342
  adapter: Readonly<GpuDebugAdapterInfo>;
@@ -266,6 +347,7 @@ interface GpuDebugSnapshot {
266
347
  dag: GpuDebugDagSnapshot;
267
348
  pipeline: GpuDebugPipelineSnapshot;
268
349
  wavefront: GpuDebugWavefrontSnapshot;
350
+ fixedSpp: GpuDebugFixedSppSnapshot;
269
351
  limitations: readonly string[];
270
352
  }
271
353
  interface GpuDebugSession {
@@ -279,6 +361,7 @@ interface GpuDebugSession {
279
361
  recordDependencyUnlock(sample: GpuDependencyUnlockSample): boolean;
280
362
  recordPipelinePhase(sample: GpuPipelinePhaseSample): boolean;
281
363
  recordWavefrontTelemetry(sample: GpuWavefrontTelemetrySample): boolean;
364
+ recordFixedSppTelemetry(sample: GpuFixedSppTelemetrySample): boolean;
282
365
  recordFrame(sample: GpuFrameSample): boolean;
283
366
  getSnapshot(): GpuDebugSnapshot;
284
367
  reset(): void;
@@ -287,9 +370,11 @@ interface GpuDebugSession {
287
370
  declare function estimateDispatchInvocations(sample: GpuDispatchSample): number;
288
371
  declare function createGpuDebugSession(options?: GpuDebugSessionOptions): GpuDebugSession;
289
372
  declare function summarizeWavefrontTelemetry(snapshot: GpuDebugWavefrontSnapshot | undefined): readonly string[];
373
+ /** Formats bounded fixed-SPP ray, timing, and telemetry-memory evidence. */
374
+ declare function summarizeFixedSppTelemetry(snapshot: GpuDebugFixedSppSnapshot | undefined): readonly string[];
290
375
 
291
376
  declare const gpuDebugQueueClasses: readonly ("render" | "simulation" | "lighting" | "post-processing" | "voxel" | "transfer" | "custom")[];
292
377
  declare const gpuResourceCategories: readonly ("custom" | "buffer" | "texture" | "bind-group" | "pipeline")[];
293
378
  declare const gpuPipelinePhases: readonly ("render" | "simulation" | "secondary-simulation" | "scene-preparation")[];
294
379
 
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 };
380
+ 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,277 @@ 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 (capturedRayCounts !== bounceHistogram.length) {
577
+ throw new Error(
578
+ "fixedSpp.rayCounts.capturedRayCounts must match the bounce histogram length."
579
+ );
580
+ }
581
+ if (status === "available" && (source === null || expectedPrimaryRays === null || observedPrimaryRays === null || secondaryRays === null || totalPathSegments === null)) {
582
+ throw new Error(
583
+ "available fixedSpp.rayCounts require a source and complete ray measurements."
584
+ );
585
+ }
586
+ if (status === "available" && bounceHistogram.reduce((total, count) => total + count, 0) !== totalPathSegments) {
587
+ throw new Error(
588
+ "available fixedSpp.rayCounts bounce histogram must sum to totalPathSegments."
589
+ );
590
+ }
591
+ return Object.freeze({
592
+ status,
593
+ source,
594
+ expectedPrimaryRays,
595
+ observedPrimaryRays,
596
+ secondaryRays,
597
+ totalPathSegments,
598
+ bounceHistogram,
599
+ capturedRayCounts,
600
+ expectedRayCounts,
601
+ reason
602
+ });
603
+ }
604
+ function normalizeFixedSppTimings(value) {
605
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
606
+ throw new Error("fixedSpp.timings must be an object.");
607
+ }
608
+ const status = assertEnumValue(
609
+ "fixedSpp.timings.status",
610
+ value.status,
611
+ FIXED_SPP_TIMING_STATUSES
612
+ );
613
+ const source = value.source === null ? null : assertEnumValue(
614
+ "fixedSpp.timings.source",
615
+ value.source,
616
+ FIXED_SPP_TIMING_SOURCES
617
+ );
618
+ const timestampQueryStatus = assertEnumValue(
619
+ "fixedSpp.timings.timestampQueryStatus",
620
+ value.timestampQueryStatus,
621
+ FIXED_SPP_TIMESTAMP_QUERY_STATUSES
622
+ );
623
+ const totalGpuTimeMs = readNullableNonNegativeNumber(
624
+ "fixedSpp.timings.totalGpuTimeMs",
625
+ value.totalGpuTimeMs
626
+ );
627
+ const totalRenderJobTimeMs = readRequiredNonNegativeNumber(
628
+ "fixedSpp.timings.totalRenderJobTimeMs",
629
+ value.totalRenderJobTimeMs
630
+ );
631
+ const classificationTimeMs = readNullableNonNegativeNumber(
632
+ "fixedSpp.timings.classificationTimeMs",
633
+ value.classificationTimeMs
634
+ );
635
+ const compactionTimeMs = readNullableNonNegativeNumber(
636
+ "fixedSpp.timings.compactionTimeMs",
637
+ value.compactionTimeMs
638
+ );
639
+ const samplingTimeMs = readNullableNonNegativeNumber(
640
+ "fixedSpp.timings.samplingTimeMs",
641
+ value.samplingTimeMs
642
+ );
643
+ const reason = normalizeEvidenceReason("fixedSpp.timings.reason", value.reason);
644
+ if (timestampQueryStatus === "available" && (status !== "available" || source !== "timestamp-query" || totalGpuTimeMs === null)) {
645
+ throw new Error(
646
+ "available timestamp-query evidence requires available timestamp timing and totalGpuTimeMs."
647
+ );
648
+ }
649
+ return Object.freeze({
650
+ status,
651
+ source,
652
+ timestampQueryStatus,
653
+ totalGpuTimeMs,
654
+ totalRenderJobTimeMs,
655
+ classificationTimeMs,
656
+ compactionTimeMs,
657
+ samplingTimeMs,
658
+ reason
659
+ });
660
+ }
661
+ function normalizeFixedSppTelemetrySample(sample) {
662
+ if (sample.signal !== void 0 && !isAbortSignalLike(sample.signal)) {
663
+ throw new Error("fixedSpp.signal must be an AbortSignal when provided.");
664
+ }
665
+ const samplesPerPixel = readRequiredPositiveInteger(
666
+ "fixedSpp.samplesPerPixel",
667
+ sample.samplesPerPixel
668
+ );
669
+ const renderedSamplesPerPixel = readRequiredPositiveInteger(
670
+ "fixedSpp.renderedSamplesPerPixel",
671
+ sample.renderedSamplesPerPixel
672
+ );
673
+ if (renderedSamplesPerPixel > samplesPerPixel) {
674
+ throw new Error(
675
+ "fixedSpp.renderedSamplesPerPixel cannot exceed fixedSpp.samplesPerPixel."
676
+ );
677
+ }
678
+ const primaryRays = readRequiredNonNegativeInteger(
679
+ "fixedSpp.primaryRays",
680
+ sample.primaryRays
681
+ );
682
+ const secondaryRays = readNullableNonNegativeInteger(
683
+ "fixedSpp.secondaryRays",
684
+ sample.secondaryRays
685
+ );
686
+ const totalPathSegments = readNullableNonNegativeInteger(
687
+ "fixedSpp.totalPathSegments",
688
+ sample.totalPathSegments
689
+ );
690
+ const rayCounts = normalizeFixedSppRayCounts(sample.rayCounts);
691
+ const timings = normalizeFixedSppTimings(sample.timings);
692
+ const telemetryMemoryBytes = readRequiredNonNegativeInteger(
693
+ "fixedSpp.telemetryMemoryBytes",
694
+ sample.telemetryMemoryBytes
695
+ );
696
+ if (secondaryRays !== rayCounts.secondaryRays) {
697
+ throw new Error(
698
+ "fixedSpp.secondaryRays must match fixedSpp.rayCounts.secondaryRays."
699
+ );
700
+ }
701
+ if (totalPathSegments !== rayCounts.totalPathSegments) {
702
+ throw new Error(
703
+ "fixedSpp.totalPathSegments must match fixedSpp.rayCounts.totalPathSegments."
704
+ );
705
+ }
706
+ if (secondaryRays === null !== (totalPathSegments === null)) {
707
+ throw new Error(
708
+ "fixedSpp.secondaryRays and fixedSpp.totalPathSegments must both be measured or both be null."
709
+ );
710
+ }
711
+ if (secondaryRays !== null && totalPathSegments !== primaryRays + secondaryRays) {
712
+ throw new Error(
713
+ "fixedSpp.totalPathSegments must equal primaryRays plus secondaryRays when measured."
714
+ );
715
+ }
716
+ if (rayCounts.expectedPrimaryRays !== null && rayCounts.expectedPrimaryRays !== primaryRays) {
717
+ throw new Error(
718
+ "fixedSpp.primaryRays must match fixedSpp.rayCounts.expectedPrimaryRays."
719
+ );
720
+ }
721
+ if (rayCounts.status === "available" && rayCounts.observedPrimaryRays !== primaryRays) {
722
+ throw new Error(
723
+ "available fixedSpp.rayCounts observedPrimaryRays must match primaryRays."
724
+ );
725
+ }
726
+ return Object.freeze({
727
+ owner: assertIdentifier("fixedSpp.owner", sample.owner),
728
+ queueClass: assertEnumValue(
729
+ "fixedSpp.queueClass",
730
+ sample.queueClass,
731
+ gpuDebugQueueClasses
732
+ ),
733
+ frameId: sample.frameId === void 0 ? void 0 : assertIdentifier("fixedSpp.frameId", sample.frameId),
734
+ samplesPerPixel,
735
+ renderedSamplesPerPixel,
736
+ primaryRays,
737
+ secondaryRays,
738
+ totalPathSegments,
739
+ rayCounts,
740
+ timings,
741
+ telemetryMemoryBytes
742
+ });
743
+ }
447
744
  function estimateDispatchInvocations(sample) {
448
745
  const normalized = normalizeDispatchSample(sample);
449
746
  return normalized.workgroups.x * normalized.workgroups.y * normalized.workgroups.z * normalized.workgroupSize.x * normalized.workgroupSize.y * normalized.workgroupSize.z;
@@ -475,6 +772,10 @@ function createGpuDebugSession(options = {}) {
475
772
  options.maxRetainedWavefrontSamples,
476
773
  DEFAULT_OPTIONS.maxRetainedWavefrontSamples
477
774
  ),
775
+ maxRetainedFixedSppSamples: clampCount(
776
+ options.maxRetainedFixedSppSamples,
777
+ DEFAULT_OPTIONS.maxRetainedFixedSppSamples
778
+ ),
478
779
  maxRetainedFrameSamples: clampCount(
479
780
  options.maxRetainedFrameSamples,
480
781
  DEFAULT_OPTIONS.maxRetainedFrameSamples
@@ -494,6 +795,7 @@ function createGpuDebugSession(options = {}) {
494
795
  const dependencyUnlockSamples = [];
495
796
  const pipelinePhaseSamples = [];
496
797
  const wavefrontSamples = [];
798
+ const fixedSppSamples = [];
497
799
  const frameSamples = [];
498
800
  let peakTrackedBytes = 0;
499
801
  const totalTrackedBytes = () => [...allocations.values()].reduce((total, allocation) => total + allocation.sizeBytes, 0);
@@ -772,6 +1074,67 @@ function createGpuDebugSession(options = {}) {
772
1074
  byHitKind: [...byHitKind.entries()].map(([kind, count]) => ({ kind, count })).sort((left, right) => right.count - left.count)
773
1075
  };
774
1076
  };
1077
+ const buildFixedSppSnapshot = () => {
1078
+ const primaryRays = fixedSppSamples.map((sample) => sample.primaryRays);
1079
+ const measuredSecondaryRays = fixedSppSamples.map((sample) => sample.secondaryRays).filter((value) => value !== null);
1080
+ const measuredPathSegments = fixedSppSamples.map((sample) => sample.totalPathSegments).filter((value) => value !== null);
1081
+ const gpuTimes = fixedSppSamples.map((sample) => sample.timings.totalGpuTimeMs).filter((value) => value !== null);
1082
+ const renderJobTimes = fixedSppSamples.map(
1083
+ (sample) => sample.timings.totalRenderJobTimeMs
1084
+ );
1085
+ const classificationTimes = fixedSppSamples.map((sample) => sample.timings.classificationTimeMs).filter((value) => value !== null);
1086
+ const compactionTimes = fixedSppSamples.map((sample) => sample.timings.compactionTimeMs).filter((value) => value !== null);
1087
+ const samplingTimes = fixedSppSamples.map((sample) => sample.timings.samplingTimeMs).filter((value) => value !== null);
1088
+ const telemetryMemory = fixedSppSamples.map(
1089
+ (sample) => sample.telemetryMemoryBytes
1090
+ );
1091
+ const byRayCountStatus = /* @__PURE__ */ new Map();
1092
+ const byTimingStatus = /* @__PURE__ */ new Map();
1093
+ const byTimestampQueryStatus = /* @__PURE__ */ new Map();
1094
+ for (const sample of fixedSppSamples) {
1095
+ pushAggregate(byRayCountStatus, sample.rayCounts.status, 1);
1096
+ pushAggregate(byTimingStatus, sample.timings.status, 1);
1097
+ pushAggregate(
1098
+ byTimestampQueryStatus,
1099
+ sample.timings.timestampQueryStatus,
1100
+ 1
1101
+ );
1102
+ }
1103
+ return {
1104
+ sampleCount: fixedSppSamples.length,
1105
+ measuredRayCountSampleCount: measuredPathSegments.length,
1106
+ measuredGpuTimeSampleCount: gpuTimes.length,
1107
+ totalPrimaryRays: primaryRays.reduce((total, value) => total + value, 0),
1108
+ totalMeasuredSecondaryRays: measuredSecondaryRays.reduce(
1109
+ (total, value) => total + value,
1110
+ 0
1111
+ ),
1112
+ totalMeasuredPathSegments: measuredPathSegments.reduce(
1113
+ (total, value) => total + value,
1114
+ 0
1115
+ ),
1116
+ averagePrimaryRays: average(primaryRays),
1117
+ averageMeasuredSecondaryRays: average(measuredSecondaryRays),
1118
+ averageMeasuredPathSegments: average(measuredPathSegments),
1119
+ averageGpuTimeMs: average(gpuTimes),
1120
+ averageRenderJobTimeMs: average(renderJobTimes),
1121
+ averageClassificationTimeMs: average(classificationTimes),
1122
+ averageCompactionTimeMs: average(compactionTimes),
1123
+ averageSamplingTimeMs: average(samplingTimes),
1124
+ peakTelemetryMemoryBytes: telemetryMemory.length > 0 ? Math.max(...telemetryMemory) : 0,
1125
+ byRayCountStatus: [...byRayCountStatus.entries()].map(
1126
+ ([status, count]) => ({ status, count })
1127
+ ),
1128
+ byTimingStatus: [...byTimingStatus.entries()].map(([status, count]) => ({
1129
+ status,
1130
+ count
1131
+ })),
1132
+ byTimestampQueryStatus: [...byTimestampQueryStatus.entries()].map(
1133
+ ([status, count]) => ({ status, count })
1134
+ ),
1135
+ latest: fixedSppSamples[fixedSppSamples.length - 1]
1136
+ };
1137
+ };
775
1138
  return {
776
1139
  isEnabled() {
777
1140
  return enabled;
@@ -861,6 +1224,14 @@ function createGpuDebugSession(options = {}) {
861
1224
  trimHistory(wavefrontSamples, settings.maxRetainedWavefrontSamples);
862
1225
  return true;
863
1226
  },
1227
+ recordFixedSppTelemetry(sample) {
1228
+ if (!enabled || sample.signal?.aborted === true) {
1229
+ return false;
1230
+ }
1231
+ fixedSppSamples.push(normalizeFixedSppTelemetrySample(sample));
1232
+ trimHistory(fixedSppSamples, settings.maxRetainedFixedSppSamples);
1233
+ return true;
1234
+ },
864
1235
  recordFrame(sample) {
865
1236
  if (!enabled || sample.signal?.aborted === true) {
866
1237
  return false;
@@ -904,6 +1275,7 @@ function createGpuDebugSession(options = {}) {
904
1275
  dag: buildDagSnapshot(),
905
1276
  pipeline: buildPipelineSnapshot(),
906
1277
  wavefront: buildWavefrontSnapshot(),
1278
+ fixedSpp: buildFixedSppSnapshot(),
907
1279
  limitations: LIMITATIONS
908
1280
  };
909
1281
  return snapshot;
@@ -917,6 +1289,7 @@ function createGpuDebugSession(options = {}) {
917
1289
  dependencyUnlockSamples.splice(0, dependencyUnlockSamples.length);
918
1290
  pipelinePhaseSamples.splice(0, pipelinePhaseSamples.length);
919
1291
  wavefrontSamples.splice(0, wavefrontSamples.length);
1292
+ fixedSppSamples.splice(0, fixedSppSamples.length);
920
1293
  frameSamples.splice(0, frameSamples.length);
921
1294
  peakTrackedBytes = 0;
922
1295
  }
@@ -950,12 +1323,31 @@ function summarizeWavefrontTelemetry(snapshot) {
950
1323
  );
951
1324
  return Object.freeze(lines);
952
1325
  }
1326
+ function summarizeStatusCounts(entries) {
1327
+ return entries.length === 0 ? "none" : entries.map((entry) => `${entry.status}=${entry.count}`).join(", ");
1328
+ }
1329
+ function sampleLabel(count) {
1330
+ return count === 1 ? "sample" : "samples";
1331
+ }
1332
+ function summarizeFixedSppTelemetry(snapshot) {
1333
+ if (!snapshot || snapshot.sampleCount === 0) {
1334
+ return Object.freeze(["Fixed-SPP telemetry: no samples recorded."]);
1335
+ }
1336
+ const gpuTiming = snapshot.averageGpuTimeMs === void 0 ? "GPU unavailable from 0 samples" : `GPU avg ${snapshot.averageGpuTimeMs.toFixed(2)} ms from ${snapshot.measuredGpuTimeSampleCount} ${sampleLabel(snapshot.measuredGpuTimeSampleCount)}`;
1337
+ 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)}`;
1338
+ return Object.freeze([
1339
+ `Fixed-SPP telemetry: ${snapshot.sampleCount} ${sampleLabel(snapshot.sampleCount)}, ${snapshot.totalPrimaryRays} primary rays, ${snapshot.totalMeasuredSecondaryRays} measured secondary rays, ${snapshot.totalMeasuredPathSegments} measured path segments.`,
1340
+ `Timing: ${gpuTiming}; ${renderJobTiming}.`,
1341
+ `Evidence: ray counts ${summarizeStatusCounts(snapshot.byRayCountStatus)}; timestamp queries ${summarizeStatusCounts(snapshot.byTimestampQueryStatus)}; peak telemetry memory ${snapshot.peakTelemetryMemoryBytes} bytes.`
1342
+ ]);
1343
+ }
953
1344
  export {
954
1345
  createGpuDebugSession,
955
1346
  estimateDispatchInvocations,
956
1347
  gpuDebugQueueClasses,
957
1348
  gpuPipelinePhases,
958
1349
  gpuResourceCategories,
1350
+ summarizeFixedSppTelemetry,
959
1351
  summarizeWavefrontTelemetry
960
1352
  };
961
1353
  //# sourceMappingURL=index.js.map