@plasius/gpu-debug 0.2.5 → 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/CHANGELOG.md +18 -0
- package/README.md +30 -0
- package/dist/index.cjs +394 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +86 -1
- package/dist/index.d.ts +86 -1
- package/dist/index.js +393 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -20,6 +20,23 @@ 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.6] - 2026-08-31
|
|
24
|
+
|
|
25
|
+
- **Added**
|
|
26
|
+
- Added bounded fixed-SPP renderer telemetry ingestion and summaries for ray
|
|
27
|
+
counts, path segments, timing evidence, timestamp-query status, and telemetry
|
|
28
|
+
memory without initiating GPU readbacks.
|
|
29
|
+
- Added `summarizeFixedSppTelemetry(...)` for compact operator evidence.
|
|
30
|
+
|
|
31
|
+
- **Changed**
|
|
32
|
+
- (placeholder)
|
|
33
|
+
|
|
34
|
+
- **Fixed**
|
|
35
|
+
- (placeholder)
|
|
36
|
+
|
|
37
|
+
- **Security**
|
|
38
|
+
- (placeholder)
|
|
39
|
+
|
|
23
40
|
## [0.2.5] - 2026-08-30
|
|
24
41
|
|
|
25
42
|
- **Added**
|
|
@@ -253,3 +270,4 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
|
|
|
253
270
|
[0.2.3]: https://github.com/Plasius-LTD/gpu-debug/releases/tag/v0.2.3
|
|
254
271
|
[0.2.4]: https://github.com/Plasius-LTD/gpu-debug/releases/tag/v0.2.4
|
|
255
272
|
[0.2.5]: https://github.com/Plasius-LTD/gpu-debug/releases/tag/v0.2.5
|
|
273
|
+
[0.2.6]: https://github.com/Plasius-LTD/gpu-debug/releases/tag/v0.2.6
|
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,13 @@ 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
|
+
|
|
201
231
|
## Worker and Frame Correlation
|
|
202
232
|
|
|
203
233
|
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,277 @@ 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 (capturedRayCounts !== bounceHistogram.length) {
|
|
609
|
+
throw new Error(
|
|
610
|
+
"fixedSpp.rayCounts.capturedRayCounts must match the bounce histogram length."
|
|
611
|
+
);
|
|
612
|
+
}
|
|
613
|
+
if (status === "available" && (source === null || expectedPrimaryRays === null || observedPrimaryRays === null || secondaryRays === null || totalPathSegments === null)) {
|
|
614
|
+
throw new Error(
|
|
615
|
+
"available fixedSpp.rayCounts require a source and complete ray measurements."
|
|
616
|
+
);
|
|
617
|
+
}
|
|
618
|
+
if (status === "available" && bounceHistogram.reduce((total, count) => total + count, 0) !== totalPathSegments) {
|
|
619
|
+
throw new Error(
|
|
620
|
+
"available fixedSpp.rayCounts bounce histogram must sum to totalPathSegments."
|
|
621
|
+
);
|
|
622
|
+
}
|
|
623
|
+
return Object.freeze({
|
|
624
|
+
status,
|
|
625
|
+
source,
|
|
626
|
+
expectedPrimaryRays,
|
|
627
|
+
observedPrimaryRays,
|
|
628
|
+
secondaryRays,
|
|
629
|
+
totalPathSegments,
|
|
630
|
+
bounceHistogram,
|
|
631
|
+
capturedRayCounts,
|
|
632
|
+
expectedRayCounts,
|
|
633
|
+
reason
|
|
634
|
+
});
|
|
635
|
+
}
|
|
636
|
+
function normalizeFixedSppTimings(value) {
|
|
637
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
|
638
|
+
throw new Error("fixedSpp.timings must be an object.");
|
|
639
|
+
}
|
|
640
|
+
const status = assertEnumValue(
|
|
641
|
+
"fixedSpp.timings.status",
|
|
642
|
+
value.status,
|
|
643
|
+
FIXED_SPP_TIMING_STATUSES
|
|
644
|
+
);
|
|
645
|
+
const source = value.source === null ? null : assertEnumValue(
|
|
646
|
+
"fixedSpp.timings.source",
|
|
647
|
+
value.source,
|
|
648
|
+
FIXED_SPP_TIMING_SOURCES
|
|
649
|
+
);
|
|
650
|
+
const timestampQueryStatus = assertEnumValue(
|
|
651
|
+
"fixedSpp.timings.timestampQueryStatus",
|
|
652
|
+
value.timestampQueryStatus,
|
|
653
|
+
FIXED_SPP_TIMESTAMP_QUERY_STATUSES
|
|
654
|
+
);
|
|
655
|
+
const totalGpuTimeMs = readNullableNonNegativeNumber(
|
|
656
|
+
"fixedSpp.timings.totalGpuTimeMs",
|
|
657
|
+
value.totalGpuTimeMs
|
|
658
|
+
);
|
|
659
|
+
const totalRenderJobTimeMs = readRequiredNonNegativeNumber(
|
|
660
|
+
"fixedSpp.timings.totalRenderJobTimeMs",
|
|
661
|
+
value.totalRenderJobTimeMs
|
|
662
|
+
);
|
|
663
|
+
const classificationTimeMs = readNullableNonNegativeNumber(
|
|
664
|
+
"fixedSpp.timings.classificationTimeMs",
|
|
665
|
+
value.classificationTimeMs
|
|
666
|
+
);
|
|
667
|
+
const compactionTimeMs = readNullableNonNegativeNumber(
|
|
668
|
+
"fixedSpp.timings.compactionTimeMs",
|
|
669
|
+
value.compactionTimeMs
|
|
670
|
+
);
|
|
671
|
+
const samplingTimeMs = readNullableNonNegativeNumber(
|
|
672
|
+
"fixedSpp.timings.samplingTimeMs",
|
|
673
|
+
value.samplingTimeMs
|
|
674
|
+
);
|
|
675
|
+
const reason = normalizeEvidenceReason("fixedSpp.timings.reason", value.reason);
|
|
676
|
+
if (timestampQueryStatus === "available" && (status !== "available" || source !== "timestamp-query" || totalGpuTimeMs === null)) {
|
|
677
|
+
throw new Error(
|
|
678
|
+
"available timestamp-query evidence requires available timestamp timing and totalGpuTimeMs."
|
|
679
|
+
);
|
|
680
|
+
}
|
|
681
|
+
return Object.freeze({
|
|
682
|
+
status,
|
|
683
|
+
source,
|
|
684
|
+
timestampQueryStatus,
|
|
685
|
+
totalGpuTimeMs,
|
|
686
|
+
totalRenderJobTimeMs,
|
|
687
|
+
classificationTimeMs,
|
|
688
|
+
compactionTimeMs,
|
|
689
|
+
samplingTimeMs,
|
|
690
|
+
reason
|
|
691
|
+
});
|
|
692
|
+
}
|
|
693
|
+
function normalizeFixedSppTelemetrySample(sample) {
|
|
694
|
+
if (sample.signal !== void 0 && !isAbortSignalLike(sample.signal)) {
|
|
695
|
+
throw new Error("fixedSpp.signal must be an AbortSignal when provided.");
|
|
696
|
+
}
|
|
697
|
+
const samplesPerPixel = readRequiredPositiveInteger(
|
|
698
|
+
"fixedSpp.samplesPerPixel",
|
|
699
|
+
sample.samplesPerPixel
|
|
700
|
+
);
|
|
701
|
+
const renderedSamplesPerPixel = readRequiredPositiveInteger(
|
|
702
|
+
"fixedSpp.renderedSamplesPerPixel",
|
|
703
|
+
sample.renderedSamplesPerPixel
|
|
704
|
+
);
|
|
705
|
+
if (renderedSamplesPerPixel > samplesPerPixel) {
|
|
706
|
+
throw new Error(
|
|
707
|
+
"fixedSpp.renderedSamplesPerPixel cannot exceed fixedSpp.samplesPerPixel."
|
|
708
|
+
);
|
|
709
|
+
}
|
|
710
|
+
const primaryRays = readRequiredNonNegativeInteger(
|
|
711
|
+
"fixedSpp.primaryRays",
|
|
712
|
+
sample.primaryRays
|
|
713
|
+
);
|
|
714
|
+
const secondaryRays = readNullableNonNegativeInteger(
|
|
715
|
+
"fixedSpp.secondaryRays",
|
|
716
|
+
sample.secondaryRays
|
|
717
|
+
);
|
|
718
|
+
const totalPathSegments = readNullableNonNegativeInteger(
|
|
719
|
+
"fixedSpp.totalPathSegments",
|
|
720
|
+
sample.totalPathSegments
|
|
721
|
+
);
|
|
722
|
+
const rayCounts = normalizeFixedSppRayCounts(sample.rayCounts);
|
|
723
|
+
const timings = normalizeFixedSppTimings(sample.timings);
|
|
724
|
+
const telemetryMemoryBytes = readRequiredNonNegativeInteger(
|
|
725
|
+
"fixedSpp.telemetryMemoryBytes",
|
|
726
|
+
sample.telemetryMemoryBytes
|
|
727
|
+
);
|
|
728
|
+
if (secondaryRays !== rayCounts.secondaryRays) {
|
|
729
|
+
throw new Error(
|
|
730
|
+
"fixedSpp.secondaryRays must match fixedSpp.rayCounts.secondaryRays."
|
|
731
|
+
);
|
|
732
|
+
}
|
|
733
|
+
if (totalPathSegments !== rayCounts.totalPathSegments) {
|
|
734
|
+
throw new Error(
|
|
735
|
+
"fixedSpp.totalPathSegments must match fixedSpp.rayCounts.totalPathSegments."
|
|
736
|
+
);
|
|
737
|
+
}
|
|
738
|
+
if (secondaryRays === null !== (totalPathSegments === null)) {
|
|
739
|
+
throw new Error(
|
|
740
|
+
"fixedSpp.secondaryRays and fixedSpp.totalPathSegments must both be measured or both be null."
|
|
741
|
+
);
|
|
742
|
+
}
|
|
743
|
+
if (secondaryRays !== null && totalPathSegments !== primaryRays + secondaryRays) {
|
|
744
|
+
throw new Error(
|
|
745
|
+
"fixedSpp.totalPathSegments must equal primaryRays plus secondaryRays when measured."
|
|
746
|
+
);
|
|
747
|
+
}
|
|
748
|
+
if (rayCounts.expectedPrimaryRays !== null && rayCounts.expectedPrimaryRays !== primaryRays) {
|
|
749
|
+
throw new Error(
|
|
750
|
+
"fixedSpp.primaryRays must match fixedSpp.rayCounts.expectedPrimaryRays."
|
|
751
|
+
);
|
|
752
|
+
}
|
|
753
|
+
if (rayCounts.status === "available" && rayCounts.observedPrimaryRays !== primaryRays) {
|
|
754
|
+
throw new Error(
|
|
755
|
+
"available fixedSpp.rayCounts observedPrimaryRays must match primaryRays."
|
|
756
|
+
);
|
|
757
|
+
}
|
|
758
|
+
return Object.freeze({
|
|
759
|
+
owner: assertIdentifier("fixedSpp.owner", sample.owner),
|
|
760
|
+
queueClass: assertEnumValue(
|
|
761
|
+
"fixedSpp.queueClass",
|
|
762
|
+
sample.queueClass,
|
|
763
|
+
gpuDebugQueueClasses
|
|
764
|
+
),
|
|
765
|
+
frameId: sample.frameId === void 0 ? void 0 : assertIdentifier("fixedSpp.frameId", sample.frameId),
|
|
766
|
+
samplesPerPixel,
|
|
767
|
+
renderedSamplesPerPixel,
|
|
768
|
+
primaryRays,
|
|
769
|
+
secondaryRays,
|
|
770
|
+
totalPathSegments,
|
|
771
|
+
rayCounts,
|
|
772
|
+
timings,
|
|
773
|
+
telemetryMemoryBytes
|
|
774
|
+
});
|
|
775
|
+
}
|
|
478
776
|
function estimateDispatchInvocations(sample) {
|
|
479
777
|
const normalized = normalizeDispatchSample(sample);
|
|
480
778
|
return normalized.workgroups.x * normalized.workgroups.y * normalized.workgroups.z * normalized.workgroupSize.x * normalized.workgroupSize.y * normalized.workgroupSize.z;
|
|
@@ -506,6 +804,10 @@ function createGpuDebugSession(options = {}) {
|
|
|
506
804
|
options.maxRetainedWavefrontSamples,
|
|
507
805
|
DEFAULT_OPTIONS.maxRetainedWavefrontSamples
|
|
508
806
|
),
|
|
807
|
+
maxRetainedFixedSppSamples: clampCount(
|
|
808
|
+
options.maxRetainedFixedSppSamples,
|
|
809
|
+
DEFAULT_OPTIONS.maxRetainedFixedSppSamples
|
|
810
|
+
),
|
|
509
811
|
maxRetainedFrameSamples: clampCount(
|
|
510
812
|
options.maxRetainedFrameSamples,
|
|
511
813
|
DEFAULT_OPTIONS.maxRetainedFrameSamples
|
|
@@ -525,6 +827,7 @@ function createGpuDebugSession(options = {}) {
|
|
|
525
827
|
const dependencyUnlockSamples = [];
|
|
526
828
|
const pipelinePhaseSamples = [];
|
|
527
829
|
const wavefrontSamples = [];
|
|
830
|
+
const fixedSppSamples = [];
|
|
528
831
|
const frameSamples = [];
|
|
529
832
|
let peakTrackedBytes = 0;
|
|
530
833
|
const totalTrackedBytes = () => [...allocations.values()].reduce((total, allocation) => total + allocation.sizeBytes, 0);
|
|
@@ -803,6 +1106,67 @@ function createGpuDebugSession(options = {}) {
|
|
|
803
1106
|
byHitKind: [...byHitKind.entries()].map(([kind, count]) => ({ kind, count })).sort((left, right) => right.count - left.count)
|
|
804
1107
|
};
|
|
805
1108
|
};
|
|
1109
|
+
const buildFixedSppSnapshot = () => {
|
|
1110
|
+
const primaryRays = fixedSppSamples.map((sample) => sample.primaryRays);
|
|
1111
|
+
const measuredSecondaryRays = fixedSppSamples.map((sample) => sample.secondaryRays).filter((value) => value !== null);
|
|
1112
|
+
const measuredPathSegments = fixedSppSamples.map((sample) => sample.totalPathSegments).filter((value) => value !== null);
|
|
1113
|
+
const gpuTimes = fixedSppSamples.map((sample) => sample.timings.totalGpuTimeMs).filter((value) => value !== null);
|
|
1114
|
+
const renderJobTimes = fixedSppSamples.map(
|
|
1115
|
+
(sample) => sample.timings.totalRenderJobTimeMs
|
|
1116
|
+
);
|
|
1117
|
+
const classificationTimes = fixedSppSamples.map((sample) => sample.timings.classificationTimeMs).filter((value) => value !== null);
|
|
1118
|
+
const compactionTimes = fixedSppSamples.map((sample) => sample.timings.compactionTimeMs).filter((value) => value !== null);
|
|
1119
|
+
const samplingTimes = fixedSppSamples.map((sample) => sample.timings.samplingTimeMs).filter((value) => value !== null);
|
|
1120
|
+
const telemetryMemory = fixedSppSamples.map(
|
|
1121
|
+
(sample) => sample.telemetryMemoryBytes
|
|
1122
|
+
);
|
|
1123
|
+
const byRayCountStatus = /* @__PURE__ */ new Map();
|
|
1124
|
+
const byTimingStatus = /* @__PURE__ */ new Map();
|
|
1125
|
+
const byTimestampQueryStatus = /* @__PURE__ */ new Map();
|
|
1126
|
+
for (const sample of fixedSppSamples) {
|
|
1127
|
+
pushAggregate(byRayCountStatus, sample.rayCounts.status, 1);
|
|
1128
|
+
pushAggregate(byTimingStatus, sample.timings.status, 1);
|
|
1129
|
+
pushAggregate(
|
|
1130
|
+
byTimestampQueryStatus,
|
|
1131
|
+
sample.timings.timestampQueryStatus,
|
|
1132
|
+
1
|
|
1133
|
+
);
|
|
1134
|
+
}
|
|
1135
|
+
return {
|
|
1136
|
+
sampleCount: fixedSppSamples.length,
|
|
1137
|
+
measuredRayCountSampleCount: measuredPathSegments.length,
|
|
1138
|
+
measuredGpuTimeSampleCount: gpuTimes.length,
|
|
1139
|
+
totalPrimaryRays: primaryRays.reduce((total, value) => total + value, 0),
|
|
1140
|
+
totalMeasuredSecondaryRays: measuredSecondaryRays.reduce(
|
|
1141
|
+
(total, value) => total + value,
|
|
1142
|
+
0
|
|
1143
|
+
),
|
|
1144
|
+
totalMeasuredPathSegments: measuredPathSegments.reduce(
|
|
1145
|
+
(total, value) => total + value,
|
|
1146
|
+
0
|
|
1147
|
+
),
|
|
1148
|
+
averagePrimaryRays: average(primaryRays),
|
|
1149
|
+
averageMeasuredSecondaryRays: average(measuredSecondaryRays),
|
|
1150
|
+
averageMeasuredPathSegments: average(measuredPathSegments),
|
|
1151
|
+
averageGpuTimeMs: average(gpuTimes),
|
|
1152
|
+
averageRenderJobTimeMs: average(renderJobTimes),
|
|
1153
|
+
averageClassificationTimeMs: average(classificationTimes),
|
|
1154
|
+
averageCompactionTimeMs: average(compactionTimes),
|
|
1155
|
+
averageSamplingTimeMs: average(samplingTimes),
|
|
1156
|
+
peakTelemetryMemoryBytes: telemetryMemory.length > 0 ? Math.max(...telemetryMemory) : 0,
|
|
1157
|
+
byRayCountStatus: [...byRayCountStatus.entries()].map(
|
|
1158
|
+
([status, count]) => ({ status, count })
|
|
1159
|
+
),
|
|
1160
|
+
byTimingStatus: [...byTimingStatus.entries()].map(([status, count]) => ({
|
|
1161
|
+
status,
|
|
1162
|
+
count
|
|
1163
|
+
})),
|
|
1164
|
+
byTimestampQueryStatus: [...byTimestampQueryStatus.entries()].map(
|
|
1165
|
+
([status, count]) => ({ status, count })
|
|
1166
|
+
),
|
|
1167
|
+
latest: fixedSppSamples[fixedSppSamples.length - 1]
|
|
1168
|
+
};
|
|
1169
|
+
};
|
|
806
1170
|
return {
|
|
807
1171
|
isEnabled() {
|
|
808
1172
|
return enabled;
|
|
@@ -892,6 +1256,14 @@ function createGpuDebugSession(options = {}) {
|
|
|
892
1256
|
trimHistory(wavefrontSamples, settings.maxRetainedWavefrontSamples);
|
|
893
1257
|
return true;
|
|
894
1258
|
},
|
|
1259
|
+
recordFixedSppTelemetry(sample) {
|
|
1260
|
+
if (!enabled || sample.signal?.aborted === true) {
|
|
1261
|
+
return false;
|
|
1262
|
+
}
|
|
1263
|
+
fixedSppSamples.push(normalizeFixedSppTelemetrySample(sample));
|
|
1264
|
+
trimHistory(fixedSppSamples, settings.maxRetainedFixedSppSamples);
|
|
1265
|
+
return true;
|
|
1266
|
+
},
|
|
895
1267
|
recordFrame(sample) {
|
|
896
1268
|
if (!enabled || sample.signal?.aborted === true) {
|
|
897
1269
|
return false;
|
|
@@ -935,6 +1307,7 @@ function createGpuDebugSession(options = {}) {
|
|
|
935
1307
|
dag: buildDagSnapshot(),
|
|
936
1308
|
pipeline: buildPipelineSnapshot(),
|
|
937
1309
|
wavefront: buildWavefrontSnapshot(),
|
|
1310
|
+
fixedSpp: buildFixedSppSnapshot(),
|
|
938
1311
|
limitations: LIMITATIONS
|
|
939
1312
|
};
|
|
940
1313
|
return snapshot;
|
|
@@ -948,6 +1321,7 @@ function createGpuDebugSession(options = {}) {
|
|
|
948
1321
|
dependencyUnlockSamples.splice(0, dependencyUnlockSamples.length);
|
|
949
1322
|
pipelinePhaseSamples.splice(0, pipelinePhaseSamples.length);
|
|
950
1323
|
wavefrontSamples.splice(0, wavefrontSamples.length);
|
|
1324
|
+
fixedSppSamples.splice(0, fixedSppSamples.length);
|
|
951
1325
|
frameSamples.splice(0, frameSamples.length);
|
|
952
1326
|
peakTrackedBytes = 0;
|
|
953
1327
|
}
|
|
@@ -981,6 +1355,24 @@ function summarizeWavefrontTelemetry(snapshot) {
|
|
|
981
1355
|
);
|
|
982
1356
|
return Object.freeze(lines);
|
|
983
1357
|
}
|
|
1358
|
+
function summarizeStatusCounts(entries) {
|
|
1359
|
+
return entries.length === 0 ? "none" : entries.map((entry) => `${entry.status}=${entry.count}`).join(", ");
|
|
1360
|
+
}
|
|
1361
|
+
function sampleLabel(count) {
|
|
1362
|
+
return count === 1 ? "sample" : "samples";
|
|
1363
|
+
}
|
|
1364
|
+
function summarizeFixedSppTelemetry(snapshot) {
|
|
1365
|
+
if (!snapshot || snapshot.sampleCount === 0) {
|
|
1366
|
+
return Object.freeze(["Fixed-SPP telemetry: no samples recorded."]);
|
|
1367
|
+
}
|
|
1368
|
+
const gpuTiming = snapshot.averageGpuTimeMs === void 0 ? "GPU unavailable from 0 samples" : `GPU avg ${snapshot.averageGpuTimeMs.toFixed(2)} ms from ${snapshot.measuredGpuTimeSampleCount} ${sampleLabel(snapshot.measuredGpuTimeSampleCount)}`;
|
|
1369
|
+
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)}`;
|
|
1370
|
+
return Object.freeze([
|
|
1371
|
+
`Fixed-SPP telemetry: ${snapshot.sampleCount} ${sampleLabel(snapshot.sampleCount)}, ${snapshot.totalPrimaryRays} primary rays, ${snapshot.totalMeasuredSecondaryRays} measured secondary rays, ${snapshot.totalMeasuredPathSegments} measured path segments.`,
|
|
1372
|
+
`Timing: ${gpuTiming}; ${renderJobTiming}.`,
|
|
1373
|
+
`Evidence: ray counts ${summarizeStatusCounts(snapshot.byRayCountStatus)}; timestamp queries ${summarizeStatusCounts(snapshot.byTimestampQueryStatus)}; peak telemetry memory ${snapshot.peakTelemetryMemoryBytes} bytes.`
|
|
1374
|
+
]);
|
|
1375
|
+
}
|
|
984
1376
|
// Annotate the CommonJS export names for ESM import in node:
|
|
985
1377
|
0 && (module.exports = {
|
|
986
1378
|
createGpuDebugSession,
|
|
@@ -988,6 +1380,7 @@ function summarizeWavefrontTelemetry(snapshot) {
|
|
|
988
1380
|
gpuDebugQueueClasses,
|
|
989
1381
|
gpuPipelinePhases,
|
|
990
1382
|
gpuResourceCategories,
|
|
1383
|
+
summarizeFixedSppTelemetry,
|
|
991
1384
|
summarizeWavefrontTelemetry
|
|
992
1385
|
});
|
|
993
1386
|
//# sourceMappingURL=index.cjs.map
|