@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 +36 -0
- package/README.md +36 -0
- package/dist/index.cjs +399 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +88 -1
- package/dist/index.d.ts +88 -1
- package/dist/index.js +398 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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
|