@plasius/gpu-performance 0.1.14 → 0.1.16
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 +52 -0
- package/dist/index.cjs +83 -9
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +20 -1
- package/dist/index.d.ts +20 -1
- package/dist/index.js +83 -9
- package/dist/index.js.map +1 -1
- package/package.json +9 -6
package/dist/index.d.cts
CHANGED
|
@@ -111,6 +111,8 @@ interface FrameTargetNegotiationOptions {
|
|
|
111
111
|
preferredFrameRates?: readonly number[];
|
|
112
112
|
minimumFrameRate?: number;
|
|
113
113
|
maximumFrameRate?: number;
|
|
114
|
+
/** Optional execution reserve in (0, 1]; omission preserves legacy thresholds. */
|
|
115
|
+
frameBudgetRatio?: number;
|
|
114
116
|
}
|
|
115
117
|
/**
|
|
116
118
|
* Negotiated frame target and guardrails used by the control loop.
|
|
@@ -231,6 +233,8 @@ interface PerformanceModuleAdapter<Payload = unknown> {
|
|
|
231
233
|
authority: ModuleAuthority;
|
|
232
234
|
importance: ModuleImportance;
|
|
233
235
|
getSnapshot(): PerformanceModuleSnapshot<Payload>;
|
|
236
|
+
/** Optional upgrade admission. A refusal retains pending governor recovery. */
|
|
237
|
+
canStepUp?(context: PerformanceAdjustmentContext): boolean;
|
|
234
238
|
stepDown(context: PerformanceAdjustmentContext): PerformanceAdjustmentRecord<Payload> | null;
|
|
235
239
|
stepUp(context: PerformanceAdjustmentContext): PerformanceAdjustmentRecord<Payload> | null;
|
|
236
240
|
}
|
|
@@ -256,8 +260,17 @@ interface QualityLadderAdapterOptions<Payload = unknown> {
|
|
|
256
260
|
importanceSignals?: Readonly<PerformanceImportanceSignals>;
|
|
257
261
|
levels: readonly ModuleQualityLevel<Payload>[];
|
|
258
262
|
initialLevel?: number | string;
|
|
263
|
+
recoveryBudget?: QualityRecoveryBudgetOptions;
|
|
259
264
|
onLevelChange?: (event: QualityLadderChangeEvent<Payload>) => void;
|
|
260
265
|
}
|
|
266
|
+
/** Opt-in measured recovery; unknown levels remain discoverable. */
|
|
267
|
+
interface QualityRecoveryBudgetOptions {
|
|
268
|
+
/** Fraction of the negotiated frame interval reserved for projected work, in (0, 1]. */
|
|
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[];
|
|
273
|
+
}
|
|
261
274
|
/**
|
|
262
275
|
* Public surface for ladder-backed adapters.
|
|
263
276
|
*/
|
|
@@ -266,6 +279,9 @@ interface QualityLadderAdapter<Payload = unknown> extends PerformanceModuleAdapt
|
|
|
266
279
|
qualityDimensions?: PerformanceQualityDimensions;
|
|
267
280
|
importanceSignals?: Readonly<PerformanceImportanceSignals>;
|
|
268
281
|
getCurrentLevel(): ModuleQualityLevel<Payload>;
|
|
282
|
+
/** Record completed execution at the current level before governor.recordFrame. */
|
|
283
|
+
recordFrameTime(frameTimeMs: number): void;
|
|
284
|
+
canStepUp(context: PerformanceAdjustmentContext): boolean;
|
|
269
285
|
}
|
|
270
286
|
/**
|
|
271
287
|
* Budget controls applied to a gpu-worker job type.
|
|
@@ -537,6 +553,9 @@ interface GpuPerformanceGovernorOptions {
|
|
|
537
553
|
device: DeviceProfileInput | DeviceProfile;
|
|
538
554
|
target?: FrameTargetNegotiationOptions;
|
|
539
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;
|
|
540
559
|
adaptation?: GovernorAdaptationOptions;
|
|
541
560
|
telemetry?: PerformanceTelemetryHooks;
|
|
542
561
|
}
|
|
@@ -626,4 +645,4 @@ declare function createWorkerJobBudgetManifestGraph(manifest: WorkerJobBudgetMan
|
|
|
626
645
|
*/
|
|
627
646
|
declare function createWorkerJobBudgetAdaptersFromManifest(manifest: WorkerJobBudgetManifest | readonly WorkerJobBudgetManifestJob[], options?: WorkerJobBudgetManifestAdapterOptions): readonly WorkerJobBudgetAdapter[];
|
|
628
647
|
|
|
629
|
-
export { type DeviceClass, type DeviceProfile, type DeviceProfileInput, type FrameSample, type FrameTargetNegotiationOptions, type FrameTargetProfile, type GovernorAdaptationOptions, type GovernorDecision, type GovernorErrorRecord, type GovernorMetrics, type GovernorState, type GovernorWorkerGraphPriorityLaneSummary, type GovernorWorkerGraphSummary, type GpuPerformanceGovernorOptions, type GpuTier, type ModuleAuthority, type ModuleImportance, type ModuleQualityLevel, type MotionClass, type PerformanceAdjustmentContext, type PerformanceAdjustmentRecord, type PerformanceBudgetMetadata, type PerformanceDomain, type PerformanceGovernor, type PerformanceImportanceSignals, type PerformanceModuleAdapter, type PerformanceModuleSnapshot, type PerformanceQualityDimensions, type PerformanceTelemetryHooks, type PressureLevel, type QualityDimension, type QualityLadderAdapter, type QualityLadderAdapterOptions, type QualityLadderChangeEvent, type RepresentationBand, type RuntimeMode, type ThermalState, type WavefrontPathTracingBudgetAdapter, type WavefrontPathTracingBudgetAdapterOptions, type WavefrontPathTracingBudgetConfig, type WavefrontPathTracingBudgetControlSummary, type WavefrontPathTracingDenoiseMode, type WavefrontPathTracingVisibilityProbeMode, type WorkerJobBudgetAdapter, type WorkerJobBudgetAdapterOptions, type WorkerJobBudgetConfig, type WorkerJobBudgetManifest, type WorkerJobBudgetManifestAdapterOptions, type WorkerJobBudgetManifestGraph, type WorkerJobBudgetManifestGraphJob, type WorkerJobBudgetManifestJob, type WorkerJobBudgetManifestPerformance, type WorkerJobBudgetManifestPriorityLane, type WorkerJobBudgetSnapshot, type WorkerJobQueueClass, type WorkerSchedulerMode, createDeviceProfile, createGpuPerformanceGovernor, createPerformanceGovernor, createQualityLadderAdapter, createWavefrontPathTracingBudgetAdapter, createWorkerJobBudgetAdapter, createWorkerJobBudgetAdaptersFromManifest, createWorkerJobBudgetManifestGraph, defaultDomainOrder, motionClasses, negotiateFrameTarget, normalizePerformanceBudgetMetadata, normalizeWavefrontPathTracingBudgetConfig, rayTracingQualityDimensions, representationBands, wavefrontPathTracingBudgetControlKeys, wavefrontPathTracingDenoiseModes, wavefrontPathTracingVisibilityProbeModes };
|
|
648
|
+
export { type DeviceClass, type DeviceProfile, type DeviceProfileInput, type FrameSample, type FrameTargetNegotiationOptions, type FrameTargetProfile, type GovernorAdaptationOptions, type GovernorDecision, type GovernorErrorRecord, type GovernorMetrics, type GovernorState, type GovernorWorkerGraphPriorityLaneSummary, type GovernorWorkerGraphSummary, type GpuPerformanceGovernorOptions, type GpuTier, type ModuleAuthority, type ModuleImportance, type ModuleQualityLevel, type MotionClass, type PerformanceAdjustmentContext, type PerformanceAdjustmentRecord, type PerformanceBudgetMetadata, type PerformanceDomain, type PerformanceGovernor, type PerformanceImportanceSignals, type PerformanceModuleAdapter, type PerformanceModuleSnapshot, type PerformanceQualityDimensions, type PerformanceTelemetryHooks, type PressureLevel, type QualityDimension, type QualityLadderAdapter, type QualityLadderAdapterOptions, type QualityLadderChangeEvent, type QualityRecoveryBudgetOptions, type RepresentationBand, type RuntimeMode, type ThermalState, type WavefrontPathTracingBudgetAdapter, type WavefrontPathTracingBudgetAdapterOptions, type WavefrontPathTracingBudgetConfig, type WavefrontPathTracingBudgetControlSummary, type WavefrontPathTracingDenoiseMode, type WavefrontPathTracingVisibilityProbeMode, type WorkerJobBudgetAdapter, type WorkerJobBudgetAdapterOptions, type WorkerJobBudgetConfig, type WorkerJobBudgetManifest, type WorkerJobBudgetManifestAdapterOptions, type WorkerJobBudgetManifestGraph, type WorkerJobBudgetManifestGraphJob, type WorkerJobBudgetManifestJob, type WorkerJobBudgetManifestPerformance, type WorkerJobBudgetManifestPriorityLane, type WorkerJobBudgetSnapshot, type WorkerJobQueueClass, type WorkerSchedulerMode, createDeviceProfile, createGpuPerformanceGovernor, createPerformanceGovernor, createQualityLadderAdapter, createWavefrontPathTracingBudgetAdapter, createWorkerJobBudgetAdapter, createWorkerJobBudgetAdaptersFromManifest, createWorkerJobBudgetManifestGraph, defaultDomainOrder, motionClasses, negotiateFrameTarget, normalizePerformanceBudgetMetadata, normalizeWavefrontPathTracingBudgetConfig, rayTracingQualityDimensions, representationBands, wavefrontPathTracingBudgetControlKeys, wavefrontPathTracingDenoiseModes, wavefrontPathTracingVisibilityProbeModes };
|
package/dist/index.d.ts
CHANGED
|
@@ -111,6 +111,8 @@ interface FrameTargetNegotiationOptions {
|
|
|
111
111
|
preferredFrameRates?: readonly number[];
|
|
112
112
|
minimumFrameRate?: number;
|
|
113
113
|
maximumFrameRate?: number;
|
|
114
|
+
/** Optional execution reserve in (0, 1]; omission preserves legacy thresholds. */
|
|
115
|
+
frameBudgetRatio?: number;
|
|
114
116
|
}
|
|
115
117
|
/**
|
|
116
118
|
* Negotiated frame target and guardrails used by the control loop.
|
|
@@ -231,6 +233,8 @@ interface PerformanceModuleAdapter<Payload = unknown> {
|
|
|
231
233
|
authority: ModuleAuthority;
|
|
232
234
|
importance: ModuleImportance;
|
|
233
235
|
getSnapshot(): PerformanceModuleSnapshot<Payload>;
|
|
236
|
+
/** Optional upgrade admission. A refusal retains pending governor recovery. */
|
|
237
|
+
canStepUp?(context: PerformanceAdjustmentContext): boolean;
|
|
234
238
|
stepDown(context: PerformanceAdjustmentContext): PerformanceAdjustmentRecord<Payload> | null;
|
|
235
239
|
stepUp(context: PerformanceAdjustmentContext): PerformanceAdjustmentRecord<Payload> | null;
|
|
236
240
|
}
|
|
@@ -256,8 +260,17 @@ interface QualityLadderAdapterOptions<Payload = unknown> {
|
|
|
256
260
|
importanceSignals?: Readonly<PerformanceImportanceSignals>;
|
|
257
261
|
levels: readonly ModuleQualityLevel<Payload>[];
|
|
258
262
|
initialLevel?: number | string;
|
|
263
|
+
recoveryBudget?: QualityRecoveryBudgetOptions;
|
|
259
264
|
onLevelChange?: (event: QualityLadderChangeEvent<Payload>) => void;
|
|
260
265
|
}
|
|
266
|
+
/** Opt-in measured recovery; unknown levels remain discoverable. */
|
|
267
|
+
interface QualityRecoveryBudgetOptions {
|
|
268
|
+
/** Fraction of the negotiated frame interval reserved for projected work, in (0, 1]. */
|
|
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[];
|
|
273
|
+
}
|
|
261
274
|
/**
|
|
262
275
|
* Public surface for ladder-backed adapters.
|
|
263
276
|
*/
|
|
@@ -266,6 +279,9 @@ interface QualityLadderAdapter<Payload = unknown> extends PerformanceModuleAdapt
|
|
|
266
279
|
qualityDimensions?: PerformanceQualityDimensions;
|
|
267
280
|
importanceSignals?: Readonly<PerformanceImportanceSignals>;
|
|
268
281
|
getCurrentLevel(): ModuleQualityLevel<Payload>;
|
|
282
|
+
/** Record completed execution at the current level before governor.recordFrame. */
|
|
283
|
+
recordFrameTime(frameTimeMs: number): void;
|
|
284
|
+
canStepUp(context: PerformanceAdjustmentContext): boolean;
|
|
269
285
|
}
|
|
270
286
|
/**
|
|
271
287
|
* Budget controls applied to a gpu-worker job type.
|
|
@@ -537,6 +553,9 @@ interface GpuPerformanceGovernorOptions {
|
|
|
537
553
|
device: DeviceProfileInput | DeviceProfile;
|
|
538
554
|
target?: FrameTargetNegotiationOptions;
|
|
539
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;
|
|
540
559
|
adaptation?: GovernorAdaptationOptions;
|
|
541
560
|
telemetry?: PerformanceTelemetryHooks;
|
|
542
561
|
}
|
|
@@ -626,4 +645,4 @@ declare function createWorkerJobBudgetManifestGraph(manifest: WorkerJobBudgetMan
|
|
|
626
645
|
*/
|
|
627
646
|
declare function createWorkerJobBudgetAdaptersFromManifest(manifest: WorkerJobBudgetManifest | readonly WorkerJobBudgetManifestJob[], options?: WorkerJobBudgetManifestAdapterOptions): readonly WorkerJobBudgetAdapter[];
|
|
628
647
|
|
|
629
|
-
export { type DeviceClass, type DeviceProfile, type DeviceProfileInput, type FrameSample, type FrameTargetNegotiationOptions, type FrameTargetProfile, type GovernorAdaptationOptions, type GovernorDecision, type GovernorErrorRecord, type GovernorMetrics, type GovernorState, type GovernorWorkerGraphPriorityLaneSummary, type GovernorWorkerGraphSummary, type GpuPerformanceGovernorOptions, type GpuTier, type ModuleAuthority, type ModuleImportance, type ModuleQualityLevel, type MotionClass, type PerformanceAdjustmentContext, type PerformanceAdjustmentRecord, type PerformanceBudgetMetadata, type PerformanceDomain, type PerformanceGovernor, type PerformanceImportanceSignals, type PerformanceModuleAdapter, type PerformanceModuleSnapshot, type PerformanceQualityDimensions, type PerformanceTelemetryHooks, type PressureLevel, type QualityDimension, type QualityLadderAdapter, type QualityLadderAdapterOptions, type QualityLadderChangeEvent, type RepresentationBand, type RuntimeMode, type ThermalState, type WavefrontPathTracingBudgetAdapter, type WavefrontPathTracingBudgetAdapterOptions, type WavefrontPathTracingBudgetConfig, type WavefrontPathTracingBudgetControlSummary, type WavefrontPathTracingDenoiseMode, type WavefrontPathTracingVisibilityProbeMode, type WorkerJobBudgetAdapter, type WorkerJobBudgetAdapterOptions, type WorkerJobBudgetConfig, type WorkerJobBudgetManifest, type WorkerJobBudgetManifestAdapterOptions, type WorkerJobBudgetManifestGraph, type WorkerJobBudgetManifestGraphJob, type WorkerJobBudgetManifestJob, type WorkerJobBudgetManifestPerformance, type WorkerJobBudgetManifestPriorityLane, type WorkerJobBudgetSnapshot, type WorkerJobQueueClass, type WorkerSchedulerMode, createDeviceProfile, createGpuPerformanceGovernor, createPerformanceGovernor, createQualityLadderAdapter, createWavefrontPathTracingBudgetAdapter, createWorkerJobBudgetAdapter, createWorkerJobBudgetAdaptersFromManifest, createWorkerJobBudgetManifestGraph, defaultDomainOrder, motionClasses, negotiateFrameTarget, normalizePerformanceBudgetMetadata, normalizeWavefrontPathTracingBudgetConfig, rayTracingQualityDimensions, representationBands, wavefrontPathTracingBudgetControlKeys, wavefrontPathTracingDenoiseModes, wavefrontPathTracingVisibilityProbeModes };
|
|
648
|
+
export { type DeviceClass, type DeviceProfile, type DeviceProfileInput, type FrameSample, type FrameTargetNegotiationOptions, type FrameTargetProfile, type GovernorAdaptationOptions, type GovernorDecision, type GovernorErrorRecord, type GovernorMetrics, type GovernorState, type GovernorWorkerGraphPriorityLaneSummary, type GovernorWorkerGraphSummary, type GpuPerformanceGovernorOptions, type GpuTier, type ModuleAuthority, type ModuleImportance, type ModuleQualityLevel, type MotionClass, type PerformanceAdjustmentContext, type PerformanceAdjustmentRecord, type PerformanceBudgetMetadata, type PerformanceDomain, type PerformanceGovernor, type PerformanceImportanceSignals, type PerformanceModuleAdapter, type PerformanceModuleSnapshot, type PerformanceQualityDimensions, type PerformanceTelemetryHooks, type PressureLevel, type QualityDimension, type QualityLadderAdapter, type QualityLadderAdapterOptions, type QualityLadderChangeEvent, type QualityRecoveryBudgetOptions, type RepresentationBand, type RuntimeMode, type ThermalState, type WavefrontPathTracingBudgetAdapter, type WavefrontPathTracingBudgetAdapterOptions, type WavefrontPathTracingBudgetConfig, type WavefrontPathTracingBudgetControlSummary, type WavefrontPathTracingDenoiseMode, type WavefrontPathTracingVisibilityProbeMode, type WorkerJobBudgetAdapter, type WorkerJobBudgetAdapterOptions, type WorkerJobBudgetConfig, type WorkerJobBudgetManifest, type WorkerJobBudgetManifestAdapterOptions, type WorkerJobBudgetManifestGraph, type WorkerJobBudgetManifestGraphJob, type WorkerJobBudgetManifestJob, type WorkerJobBudgetManifestPerformance, type WorkerJobBudgetManifestPriorityLane, type WorkerJobBudgetSnapshot, type WorkerJobQueueClass, type WorkerSchedulerMode, createDeviceProfile, createGpuPerformanceGovernor, createPerformanceGovernor, createQualityLadderAdapter, createWavefrontPathTracingBudgetAdapter, createWorkerJobBudgetAdapter, createWorkerJobBudgetAdaptersFromManifest, createWorkerJobBudgetManifestGraph, defaultDomainOrder, motionClasses, negotiateFrameTarget, normalizePerformanceBudgetMetadata, normalizeWavefrontPathTracingBudgetConfig, rayTracingQualityDimensions, representationBands, wavefrontPathTracingBudgetControlKeys, wavefrontPathTracingDenoiseModes, wavefrontPathTracingVisibilityProbeModes };
|
package/dist/index.js
CHANGED
|
@@ -166,6 +166,10 @@ function createDeviceProfile(input = {}) {
|
|
|
166
166
|
});
|
|
167
167
|
}
|
|
168
168
|
function negotiateFrameTarget(options = {}) {
|
|
169
|
+
const frameBudgetRatio = readPositiveNumber("frameBudgetRatio", options.frameBudgetRatio);
|
|
170
|
+
if (frameBudgetRatio !== void 0 && frameBudgetRatio > 1) {
|
|
171
|
+
throw new Error("frameBudgetRatio must be at most one.");
|
|
172
|
+
}
|
|
169
173
|
const mode = options.mode === void 0 ? "flat" : assertEnumValue("mode", options.mode, runtimeModes);
|
|
170
174
|
const minimumFrameRate = Math.round(
|
|
171
175
|
readPositiveNumber("minimumFrameRate", options.minimumFrameRate) ?? 60
|
|
@@ -222,8 +226,8 @@ function negotiateFrameTarget(options = {}) {
|
|
|
222
226
|
rationale.push("Immersive modes prefer headset-native cadence when the session supports it.");
|
|
223
227
|
}
|
|
224
228
|
const targetFrameTimeMs = 1e3 / targetFrameRate;
|
|
225
|
-
const downgradeMultiplier = mode === "flat" ? 1.05 : 1.03;
|
|
226
|
-
const upgradeMultiplier = mode === "flat" ? 0.92 : 0.95;
|
|
229
|
+
const downgradeMultiplier = frameBudgetRatio ?? (mode === "flat" ? 1.05 : 1.03);
|
|
230
|
+
const upgradeMultiplier = (frameBudgetRatio ?? 1) * (mode === "flat" ? 0.92 : 0.95);
|
|
227
231
|
return Object.freeze({
|
|
228
232
|
mode,
|
|
229
233
|
minimumFrameRate,
|
|
@@ -351,6 +355,42 @@ function normalizePerformanceBudgetMetadata(name, value) {
|
|
|
351
355
|
});
|
|
352
356
|
}
|
|
353
357
|
|
|
358
|
+
// src/quality-recovery.ts
|
|
359
|
+
function createMeasuredQualityRecovery(levelCount, options) {
|
|
360
|
+
const enabled = options !== void 0;
|
|
361
|
+
const headroom = enabled ? readPositiveNumber("recoveryBudget.headroomRatio", options?.headroomRatio) : 1;
|
|
362
|
+
if (headroom === void 0 || headroom > 1) {
|
|
363
|
+
throw new Error("recoveryBudget.headroomRatio must be in (0, 1].");
|
|
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
|
+
}
|
|
369
|
+
const lastTimes = new Array(levelCount);
|
|
370
|
+
const recoveryRatios = initialRatios ? [...initialRatios] : new Array(levelCount);
|
|
371
|
+
let pending;
|
|
372
|
+
return {
|
|
373
|
+
record(index, frameTimeMs) {
|
|
374
|
+
const value = readNonNegativeNumber("frameTimeMs", frameTimeMs);
|
|
375
|
+
if (value === void 0) throw new Error("frameTimeMs is required.");
|
|
376
|
+
if (!enabled || value === 0) return;
|
|
377
|
+
lastTimes[index] = value;
|
|
378
|
+
if (pending?.index === index) {
|
|
379
|
+
recoveryRatios[index] = pending.upperTime / value;
|
|
380
|
+
pending = void 0;
|
|
381
|
+
}
|
|
382
|
+
},
|
|
383
|
+
reduced(from, to) {
|
|
384
|
+
const upperTime = lastTimes[from];
|
|
385
|
+
pending = enabled && upperTime !== void 0 ? { index: to, upperTime } : void 0;
|
|
386
|
+
},
|
|
387
|
+
canRecover(index, context) {
|
|
388
|
+
const ratio = recoveryRatios[index];
|
|
389
|
+
return !enabled || ratio === void 0 || context.metrics.latestFrameTimeMs * ratio <= context.target.targetFrameTimeMs * headroom;
|
|
390
|
+
}
|
|
391
|
+
};
|
|
392
|
+
}
|
|
393
|
+
|
|
354
394
|
// src/ladder.ts
|
|
355
395
|
function resolveLevelIndex(levels, initialLevel) {
|
|
356
396
|
if (typeof initialLevel === "number") {
|
|
@@ -430,6 +470,7 @@ function createQualityLadderAdapter(options) {
|
|
|
430
470
|
const levels = [...options.levels];
|
|
431
471
|
const metadata = normalizePerformanceBudgetMetadata("budget metadata", options);
|
|
432
472
|
let currentLevelIndex = resolveLevelIndex(levels, options.initialLevel);
|
|
473
|
+
const recovery = createMeasuredQualityRecovery(levels.length, options.recoveryBudget);
|
|
433
474
|
const emitChange = (context, adjustment, previousLevelIndex) => {
|
|
434
475
|
if (typeof options.onLevelChange !== "function") {
|
|
435
476
|
return;
|
|
@@ -450,7 +491,9 @@ function createQualityLadderAdapter(options) {
|
|
|
450
491
|
return null;
|
|
451
492
|
}
|
|
452
493
|
const previousLevelIndex = currentLevelIndex;
|
|
494
|
+
if (direction === "up" && !recovery.canRecover(currentLevelIndex, context)) return null;
|
|
453
495
|
currentLevelIndex = nextLevelIndex;
|
|
496
|
+
if (direction === "down") recovery.reduced(previousLevelIndex, currentLevelIndex);
|
|
454
497
|
const adjustment = buildAdjustment(
|
|
455
498
|
direction,
|
|
456
499
|
id,
|
|
@@ -476,6 +519,12 @@ function createQualityLadderAdapter(options) {
|
|
|
476
519
|
getCurrentLevel() {
|
|
477
520
|
return levels[currentLevelIndex];
|
|
478
521
|
},
|
|
522
|
+
recordFrameTime(frameTimeMs) {
|
|
523
|
+
recovery.record(currentLevelIndex, frameTimeMs);
|
|
524
|
+
},
|
|
525
|
+
canStepUp(context) {
|
|
526
|
+
return recovery.canRecover(currentLevelIndex, context);
|
|
527
|
+
},
|
|
479
528
|
getSnapshot() {
|
|
480
529
|
return buildSnapshot(
|
|
481
530
|
id,
|
|
@@ -962,6 +1011,9 @@ function createGpuPerformanceGovernor(options) {
|
|
|
962
1011
|
throw new Error("createGpuPerformanceGovernor requires an options object.");
|
|
963
1012
|
}
|
|
964
1013
|
validateTelemetryHooks(options.telemetry);
|
|
1014
|
+
if (options.recoverInitialLevels !== void 0 && typeof options.recoverInitialLevels !== "boolean") {
|
|
1015
|
+
throw new Error("recoverInitialLevels must be a boolean.");
|
|
1016
|
+
}
|
|
965
1017
|
const device = createDeviceProfile(options.device);
|
|
966
1018
|
if (!device.supportsWebGpu) {
|
|
967
1019
|
throw new Error(
|
|
@@ -975,7 +1027,8 @@ function createGpuPerformanceGovernor(options) {
|
|
|
975
1027
|
supportedFrameRates: options.target?.supportedFrameRates ?? device.supportedFrameRates,
|
|
976
1028
|
preferredFrameRates: options.target?.preferredFrameRates,
|
|
977
1029
|
minimumFrameRate: options.target?.minimumFrameRate,
|
|
978
|
-
maximumFrameRate: options.target?.maximumFrameRate
|
|
1030
|
+
maximumFrameRate: options.target?.maximumFrameRate,
|
|
1031
|
+
frameBudgetRatio: options.target?.frameBudgetRatio
|
|
979
1032
|
});
|
|
980
1033
|
const modules = /* @__PURE__ */ new Map();
|
|
981
1034
|
if ((options.modules?.length ?? 0) > MAX_MODULE_COUNT) {
|
|
@@ -997,6 +1050,7 @@ function createGpuPerformanceGovernor(options) {
|
|
|
997
1050
|
let lastDownCycle = Number.NEGATIVE_INFINITY;
|
|
998
1051
|
let lastUpCycle = Number.NEGATIVE_INFINITY;
|
|
999
1052
|
let recoveryStack = [];
|
|
1053
|
+
const initialRecovery = new Set(options.recoverInitialLevels ? modules.keys() : []);
|
|
1000
1054
|
let recentErrors = [];
|
|
1001
1055
|
let recentFrameIds = /* @__PURE__ */ new Set();
|
|
1002
1056
|
let recentFrameIdQueue = [];
|
|
@@ -1165,25 +1219,41 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1165
1219
|
};
|
|
1166
1220
|
const attemptRecovery = (metrics, workerGraph, decisionErrors, correlationId) => {
|
|
1167
1221
|
const context = createContext("recover", "recovering", metrics, workerGraph);
|
|
1168
|
-
|
|
1169
|
-
|
|
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
|
+
};
|
|
1170
1232
|
if (!moduleId) {
|
|
1171
|
-
|
|
1233
|
+
remove();
|
|
1172
1234
|
continue;
|
|
1173
1235
|
}
|
|
1174
1236
|
const module = modules.get(moduleId);
|
|
1175
1237
|
if (!module) {
|
|
1176
|
-
|
|
1238
|
+
remove();
|
|
1177
1239
|
continue;
|
|
1178
1240
|
}
|
|
1179
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
|
+
}
|
|
1249
|
+
if (module.canStepUp?.(context) === false) continue;
|
|
1180
1250
|
const adjustment = module.stepUp(context);
|
|
1181
|
-
|
|
1251
|
+
if (index >= 0 || !adjustment) remove();
|
|
1182
1252
|
if (adjustment) {
|
|
1183
1253
|
return [adjustment];
|
|
1184
1254
|
}
|
|
1185
1255
|
} catch {
|
|
1186
|
-
|
|
1256
|
+
remove();
|
|
1187
1257
|
appendError(
|
|
1188
1258
|
createErrorRecord({
|
|
1189
1259
|
cycle,
|
|
@@ -1295,9 +1365,11 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1295
1365
|
throw new Error(`Module "${module.id}" is already registered.`);
|
|
1296
1366
|
}
|
|
1297
1367
|
modules.set(module.id, module);
|
|
1368
|
+
if (options.recoverInitialLevels) initialRecovery.add(module.id);
|
|
1298
1369
|
return () => {
|
|
1299
1370
|
modules.delete(module.id);
|
|
1300
1371
|
recoveryStack = recoveryStack.filter((id) => id !== module.id);
|
|
1372
|
+
initialRecovery.delete(module.id);
|
|
1301
1373
|
};
|
|
1302
1374
|
},
|
|
1303
1375
|
getTarget() {
|
|
@@ -1326,6 +1398,8 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1326
1398
|
lastDownCycle = Number.NEGATIVE_INFINITY;
|
|
1327
1399
|
lastUpCycle = Number.NEGATIVE_INFINITY;
|
|
1328
1400
|
recoveryStack = [];
|
|
1401
|
+
initialRecovery.clear();
|
|
1402
|
+
if (options.recoverInitialLevels) for (const id of modules.keys()) initialRecovery.add(id);
|
|
1329
1403
|
recentErrors = [];
|
|
1330
1404
|
recentFrameIds = /* @__PURE__ */ new Set();
|
|
1331
1405
|
recentFrameIdQueue = [];
|