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