@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/CHANGELOG.md +42 -0
- package/README.md +57 -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 +12 -4
- package/legal/CLA-REGISTRY.csv +0 -2
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
|