@plasius/gpu-performance 0.1.15 → 0.1.17
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 +32 -0
- package/README.md +16 -0
- package/dist/index.cjs +34 -7
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +10 -3
- package/dist/index.d.ts +10 -3
- package/dist/index.js +34 -7
- package/dist/index.js.map +1 -1
- package/package.json +15 -14
package/dist/index.d.cts
CHANGED
|
@@ -267,6 +267,9 @@ interface QualityLadderAdapterOptions<Payload = unknown> {
|
|
|
267
267
|
interface QualityRecoveryBudgetOptions {
|
|
268
268
|
/** Fraction of the negotiated frame interval reserved for projected work, in (0, 1]. */
|
|
269
269
|
headroomRatio: number;
|
|
270
|
+
/** Optional adjacent upper/lower work-cost estimates, one per upward step.
|
|
271
|
+
* Paired execution measurements supersede these estimates when available. */
|
|
272
|
+
initialCostRatios?: readonly number[];
|
|
270
273
|
}
|
|
271
274
|
/**
|
|
272
275
|
* Public surface for ladder-backed adapters.
|
|
@@ -550,6 +553,9 @@ interface GpuPerformanceGovernorOptions {
|
|
|
550
553
|
device: DeviceProfileInput | DeviceProfile;
|
|
551
554
|
target?: FrameTargetNegotiationOptions;
|
|
552
555
|
modules?: readonly PerformanceModuleAdapter[];
|
|
556
|
+
/** Recover configured initial visual levels as measured headroom permits.
|
|
557
|
+
* Defaults to false; authoritative modules still require explicit scaling permission. */
|
|
558
|
+
recoverInitialLevels?: boolean;
|
|
553
559
|
adaptation?: GovernorAdaptationOptions;
|
|
554
560
|
telemetry?: PerformanceTelemetryHooks;
|
|
555
561
|
}
|
|
@@ -599,8 +605,8 @@ declare function createDeviceProfile(input?: DeviceProfileInput): DeviceProfile;
|
|
|
599
605
|
*/
|
|
600
606
|
declare function negotiateFrameTarget(options?: FrameTargetNegotiationOptions): FrameTargetProfile;
|
|
601
607
|
|
|
602
|
-
declare const representationBands: readonly ("
|
|
603
|
-
declare const rayTracingQualityDimensions: readonly ("
|
|
608
|
+
declare const representationBands: readonly ("near" | "mid" | "far" | "horizon")[];
|
|
609
|
+
declare const rayTracingQualityDimensions: readonly ("geometry" | "animation" | "deformation" | "shading" | "shadows" | "rayTracing" | "lightingSamples" | "updateCadence" | "temporalReuse")[];
|
|
604
610
|
declare const motionClasses: readonly ("stable" | "dynamic" | "volatile")[];
|
|
605
611
|
declare function normalizePerformanceBudgetMetadata(name: string, value: unknown): Required<Omit<PerformanceBudgetMetadata, "representationBand">> & Pick<PerformanceBudgetMetadata, "representationBand">;
|
|
606
612
|
|
|
@@ -639,4 +645,5 @@ declare function createWorkerJobBudgetManifestGraph(manifest: WorkerJobBudgetMan
|
|
|
639
645
|
*/
|
|
640
646
|
declare function createWorkerJobBudgetAdaptersFromManifest(manifest: WorkerJobBudgetManifest | readonly WorkerJobBudgetManifestJob[], options?: WorkerJobBudgetManifestAdapterOptions): readonly WorkerJobBudgetAdapter[];
|
|
641
647
|
|
|
642
|
-
export {
|
|
648
|
+
export { createDeviceProfile, createGpuPerformanceGovernor, createPerformanceGovernor, createQualityLadderAdapter, createWavefrontPathTracingBudgetAdapter, createWorkerJobBudgetAdapter, createWorkerJobBudgetAdaptersFromManifest, createWorkerJobBudgetManifestGraph, defaultDomainOrder, motionClasses, negotiateFrameTarget, normalizePerformanceBudgetMetadata, normalizeWavefrontPathTracingBudgetConfig, rayTracingQualityDimensions, representationBands, wavefrontPathTracingBudgetControlKeys, wavefrontPathTracingDenoiseModes, wavefrontPathTracingVisibilityProbeModes };
|
|
649
|
+
export type { DeviceClass, DeviceProfile, DeviceProfileInput, FrameSample, FrameTargetNegotiationOptions, FrameTargetProfile, GovernorAdaptationOptions, GovernorDecision, GovernorErrorRecord, GovernorMetrics, GovernorState, GovernorWorkerGraphPriorityLaneSummary, GovernorWorkerGraphSummary, GpuPerformanceGovernorOptions, GpuTier, ModuleAuthority, ModuleImportance, ModuleQualityLevel, MotionClass, PerformanceAdjustmentContext, PerformanceAdjustmentRecord, PerformanceBudgetMetadata, PerformanceDomain, PerformanceGovernor, PerformanceImportanceSignals, PerformanceModuleAdapter, PerformanceModuleSnapshot, PerformanceQualityDimensions, PerformanceTelemetryHooks, PressureLevel, QualityDimension, QualityLadderAdapter, QualityLadderAdapterOptions, QualityLadderChangeEvent, QualityRecoveryBudgetOptions, RepresentationBand, RuntimeMode, ThermalState, WavefrontPathTracingBudgetAdapter, WavefrontPathTracingBudgetAdapterOptions, WavefrontPathTracingBudgetConfig, WavefrontPathTracingBudgetControlSummary, WavefrontPathTracingDenoiseMode, WavefrontPathTracingVisibilityProbeMode, WorkerJobBudgetAdapter, WorkerJobBudgetAdapterOptions, WorkerJobBudgetConfig, WorkerJobBudgetManifest, WorkerJobBudgetManifestAdapterOptions, WorkerJobBudgetManifestGraph, WorkerJobBudgetManifestGraphJob, WorkerJobBudgetManifestJob, WorkerJobBudgetManifestPerformance, WorkerJobBudgetManifestPriorityLane, WorkerJobBudgetSnapshot, WorkerJobQueueClass, WorkerSchedulerMode };
|
package/dist/index.d.ts
CHANGED
|
@@ -267,6 +267,9 @@ interface QualityLadderAdapterOptions<Payload = unknown> {
|
|
|
267
267
|
interface QualityRecoveryBudgetOptions {
|
|
268
268
|
/** Fraction of the negotiated frame interval reserved for projected work, in (0, 1]. */
|
|
269
269
|
headroomRatio: number;
|
|
270
|
+
/** Optional adjacent upper/lower work-cost estimates, one per upward step.
|
|
271
|
+
* Paired execution measurements supersede these estimates when available. */
|
|
272
|
+
initialCostRatios?: readonly number[];
|
|
270
273
|
}
|
|
271
274
|
/**
|
|
272
275
|
* Public surface for ladder-backed adapters.
|
|
@@ -550,6 +553,9 @@ interface GpuPerformanceGovernorOptions {
|
|
|
550
553
|
device: DeviceProfileInput | DeviceProfile;
|
|
551
554
|
target?: FrameTargetNegotiationOptions;
|
|
552
555
|
modules?: readonly PerformanceModuleAdapter[];
|
|
556
|
+
/** Recover configured initial visual levels as measured headroom permits.
|
|
557
|
+
* Defaults to false; authoritative modules still require explicit scaling permission. */
|
|
558
|
+
recoverInitialLevels?: boolean;
|
|
553
559
|
adaptation?: GovernorAdaptationOptions;
|
|
554
560
|
telemetry?: PerformanceTelemetryHooks;
|
|
555
561
|
}
|
|
@@ -599,8 +605,8 @@ declare function createDeviceProfile(input?: DeviceProfileInput): DeviceProfile;
|
|
|
599
605
|
*/
|
|
600
606
|
declare function negotiateFrameTarget(options?: FrameTargetNegotiationOptions): FrameTargetProfile;
|
|
601
607
|
|
|
602
|
-
declare const representationBands: readonly ("
|
|
603
|
-
declare const rayTracingQualityDimensions: readonly ("
|
|
608
|
+
declare const representationBands: readonly ("near" | "mid" | "far" | "horizon")[];
|
|
609
|
+
declare const rayTracingQualityDimensions: readonly ("geometry" | "animation" | "deformation" | "shading" | "shadows" | "rayTracing" | "lightingSamples" | "updateCadence" | "temporalReuse")[];
|
|
604
610
|
declare const motionClasses: readonly ("stable" | "dynamic" | "volatile")[];
|
|
605
611
|
declare function normalizePerformanceBudgetMetadata(name: string, value: unknown): Required<Omit<PerformanceBudgetMetadata, "representationBand">> & Pick<PerformanceBudgetMetadata, "representationBand">;
|
|
606
612
|
|
|
@@ -639,4 +645,5 @@ declare function createWorkerJobBudgetManifestGraph(manifest: WorkerJobBudgetMan
|
|
|
639
645
|
*/
|
|
640
646
|
declare function createWorkerJobBudgetAdaptersFromManifest(manifest: WorkerJobBudgetManifest | readonly WorkerJobBudgetManifestJob[], options?: WorkerJobBudgetManifestAdapterOptions): readonly WorkerJobBudgetAdapter[];
|
|
641
647
|
|
|
642
|
-
export {
|
|
648
|
+
export { createDeviceProfile, createGpuPerformanceGovernor, createPerformanceGovernor, createQualityLadderAdapter, createWavefrontPathTracingBudgetAdapter, createWorkerJobBudgetAdapter, createWorkerJobBudgetAdaptersFromManifest, createWorkerJobBudgetManifestGraph, defaultDomainOrder, motionClasses, negotiateFrameTarget, normalizePerformanceBudgetMetadata, normalizeWavefrontPathTracingBudgetConfig, rayTracingQualityDimensions, representationBands, wavefrontPathTracingBudgetControlKeys, wavefrontPathTracingDenoiseModes, wavefrontPathTracingVisibilityProbeModes };
|
|
649
|
+
export type { DeviceClass, DeviceProfile, DeviceProfileInput, FrameSample, FrameTargetNegotiationOptions, FrameTargetProfile, GovernorAdaptationOptions, GovernorDecision, GovernorErrorRecord, GovernorMetrics, GovernorState, GovernorWorkerGraphPriorityLaneSummary, GovernorWorkerGraphSummary, GpuPerformanceGovernorOptions, GpuTier, ModuleAuthority, ModuleImportance, ModuleQualityLevel, MotionClass, PerformanceAdjustmentContext, PerformanceAdjustmentRecord, PerformanceBudgetMetadata, PerformanceDomain, PerformanceGovernor, PerformanceImportanceSignals, PerformanceModuleAdapter, PerformanceModuleSnapshot, PerformanceQualityDimensions, PerformanceTelemetryHooks, PressureLevel, QualityDimension, QualityLadderAdapter, QualityLadderAdapterOptions, QualityLadderChangeEvent, QualityRecoveryBudgetOptions, RepresentationBand, RuntimeMode, ThermalState, WavefrontPathTracingBudgetAdapter, WavefrontPathTracingBudgetAdapterOptions, WavefrontPathTracingBudgetConfig, WavefrontPathTracingBudgetControlSummary, WavefrontPathTracingDenoiseMode, WavefrontPathTracingVisibilityProbeMode, WorkerJobBudgetAdapter, WorkerJobBudgetAdapterOptions, WorkerJobBudgetConfig, WorkerJobBudgetManifest, WorkerJobBudgetManifestAdapterOptions, WorkerJobBudgetManifestGraph, WorkerJobBudgetManifestGraphJob, WorkerJobBudgetManifestJob, WorkerJobBudgetManifestPerformance, WorkerJobBudgetManifestPriorityLane, WorkerJobBudgetSnapshot, WorkerJobQueueClass, WorkerSchedulerMode };
|
package/dist/index.js
CHANGED
|
@@ -362,8 +362,12 @@ function createMeasuredQualityRecovery(levelCount, options) {
|
|
|
362
362
|
if (headroom === void 0 || headroom > 1) {
|
|
363
363
|
throw new Error("recoveryBudget.headroomRatio must be in (0, 1].");
|
|
364
364
|
}
|
|
365
|
+
const initialRatios = options?.initialCostRatios;
|
|
366
|
+
if (initialRatios !== void 0 && (!Array.isArray(initialRatios) || initialRatios.length !== levelCount - 1 || Array.from(initialRatios).some((value) => typeof value !== "number" || !Number.isFinite(value) || value <= 0))) {
|
|
367
|
+
throw new Error("recoveryBudget.initialCostRatios must contain one finite positive ratio per upward step.");
|
|
368
|
+
}
|
|
365
369
|
const lastTimes = new Array(levelCount);
|
|
366
|
-
const recoveryRatios = new Array(levelCount);
|
|
370
|
+
const recoveryRatios = initialRatios ? [...initialRatios] : new Array(levelCount);
|
|
367
371
|
let pending;
|
|
368
372
|
return {
|
|
369
373
|
record(index, frameTimeMs) {
|
|
@@ -1007,6 +1011,9 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1007
1011
|
throw new Error("createGpuPerformanceGovernor requires an options object.");
|
|
1008
1012
|
}
|
|
1009
1013
|
validateTelemetryHooks(options.telemetry);
|
|
1014
|
+
if (options.recoverInitialLevels !== void 0 && typeof options.recoverInitialLevels !== "boolean") {
|
|
1015
|
+
throw new Error("recoverInitialLevels must be a boolean.");
|
|
1016
|
+
}
|
|
1010
1017
|
const device = createDeviceProfile(options.device);
|
|
1011
1018
|
if (!device.supportsWebGpu) {
|
|
1012
1019
|
throw new Error(
|
|
@@ -1043,6 +1050,7 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1043
1050
|
let lastDownCycle = Number.NEGATIVE_INFINITY;
|
|
1044
1051
|
let lastUpCycle = Number.NEGATIVE_INFINITY;
|
|
1045
1052
|
let recoveryStack = [];
|
|
1053
|
+
const initialRecovery = new Set(options.recoverInitialLevels ? modules.keys() : []);
|
|
1046
1054
|
let recentErrors = [];
|
|
1047
1055
|
let recentFrameIds = /* @__PURE__ */ new Set();
|
|
1048
1056
|
let recentFrameIdQueue = [];
|
|
@@ -1211,26 +1219,41 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1211
1219
|
};
|
|
1212
1220
|
const attemptRecovery = (metrics, workerGraph, decisionErrors, correlationId) => {
|
|
1213
1221
|
const context = createContext("recover", "recovering", metrics, workerGraph);
|
|
1214
|
-
|
|
1215
|
-
|
|
1222
|
+
const pending = recoveryStack.map((moduleId, index) => ({ moduleId, index })).reverse();
|
|
1223
|
+
const reduced = new Set(recoveryStack);
|
|
1224
|
+
for (const moduleId of initialRecovery) {
|
|
1225
|
+
if (!reduced.has(moduleId)) pending.push({ moduleId, index: -1 });
|
|
1226
|
+
}
|
|
1227
|
+
for (const { moduleId, index } of pending) {
|
|
1228
|
+
const remove = () => {
|
|
1229
|
+
if (index >= 0) recoveryStack.splice(index, 1);
|
|
1230
|
+
else initialRecovery.delete(moduleId);
|
|
1231
|
+
};
|
|
1216
1232
|
if (!moduleId) {
|
|
1217
|
-
|
|
1233
|
+
remove();
|
|
1218
1234
|
continue;
|
|
1219
1235
|
}
|
|
1220
1236
|
const module = modules.get(moduleId);
|
|
1221
1237
|
if (!module) {
|
|
1222
|
-
|
|
1238
|
+
remove();
|
|
1223
1239
|
continue;
|
|
1224
1240
|
}
|
|
1225
1241
|
try {
|
|
1242
|
+
if (index < 0) {
|
|
1243
|
+
const snapshot = module.getSnapshot();
|
|
1244
|
+
if (snapshot.isAtMaximum || snapshot.authority === "authoritative" && !adaptation.allowAuthoritativeScaling) {
|
|
1245
|
+
remove();
|
|
1246
|
+
continue;
|
|
1247
|
+
}
|
|
1248
|
+
}
|
|
1226
1249
|
if (module.canStepUp?.(context) === false) continue;
|
|
1227
1250
|
const adjustment = module.stepUp(context);
|
|
1228
|
-
|
|
1251
|
+
if (index >= 0 || !adjustment) remove();
|
|
1229
1252
|
if (adjustment) {
|
|
1230
1253
|
return [adjustment];
|
|
1231
1254
|
}
|
|
1232
1255
|
} catch {
|
|
1233
|
-
|
|
1256
|
+
remove();
|
|
1234
1257
|
appendError(
|
|
1235
1258
|
createErrorRecord({
|
|
1236
1259
|
cycle,
|
|
@@ -1342,9 +1365,11 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1342
1365
|
throw new Error(`Module "${module.id}" is already registered.`);
|
|
1343
1366
|
}
|
|
1344
1367
|
modules.set(module.id, module);
|
|
1368
|
+
if (options.recoverInitialLevels) initialRecovery.add(module.id);
|
|
1345
1369
|
return () => {
|
|
1346
1370
|
modules.delete(module.id);
|
|
1347
1371
|
recoveryStack = recoveryStack.filter((id) => id !== module.id);
|
|
1372
|
+
initialRecovery.delete(module.id);
|
|
1348
1373
|
};
|
|
1349
1374
|
},
|
|
1350
1375
|
getTarget() {
|
|
@@ -1373,6 +1398,8 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1373
1398
|
lastDownCycle = Number.NEGATIVE_INFINITY;
|
|
1374
1399
|
lastUpCycle = Number.NEGATIVE_INFINITY;
|
|
1375
1400
|
recoveryStack = [];
|
|
1401
|
+
initialRecovery.clear();
|
|
1402
|
+
if (options.recoverInitialLevels) for (const id of modules.keys()) initialRecovery.add(id);
|
|
1376
1403
|
recentErrors = [];
|
|
1377
1404
|
recentFrameIds = /* @__PURE__ */ new Set();
|
|
1378
1405
|
recentFrameIdQueue = [];
|