@plasius/gpu-performance 0.1.13 → 0.1.15

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/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,14 @@ 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
+ }
261
271
  /**
262
272
  * Public surface for ladder-backed adapters.
263
273
  */
@@ -266,6 +276,9 @@ interface QualityLadderAdapter<Payload = unknown> extends PerformanceModuleAdapt
266
276
  qualityDimensions?: PerformanceQualityDimensions;
267
277
  importanceSignals?: Readonly<PerformanceImportanceSignals>;
268
278
  getCurrentLevel(): ModuleQualityLevel<Payload>;
279
+ /** Record completed execution at the current level before governor.recordFrame. */
280
+ recordFrameTime(frameTimeMs: number): void;
281
+ canStepUp(context: PerformanceAdjustmentContext): boolean;
269
282
  }
270
283
  /**
271
284
  * Budget controls applied to a gpu-worker job type.
@@ -626,4 +639,4 @@ declare function createWorkerJobBudgetManifestGraph(manifest: WorkerJobBudgetMan
626
639
  */
627
640
  declare function createWorkerJobBudgetAdaptersFromManifest(manifest: WorkerJobBudgetManifest | readonly WorkerJobBudgetManifestJob[], options?: WorkerJobBudgetManifestAdapterOptions): readonly WorkerJobBudgetAdapter[];
628
641
 
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 };
642
+ 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,14 @@ 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
+ }
261
271
  /**
262
272
  * Public surface for ladder-backed adapters.
263
273
  */
@@ -266,6 +276,9 @@ interface QualityLadderAdapter<Payload = unknown> extends PerformanceModuleAdapt
266
276
  qualityDimensions?: PerformanceQualityDimensions;
267
277
  importanceSignals?: Readonly<PerformanceImportanceSignals>;
268
278
  getCurrentLevel(): ModuleQualityLevel<Payload>;
279
+ /** Record completed execution at the current level before governor.recordFrame. */
280
+ recordFrameTime(frameTimeMs: number): void;
281
+ canStepUp(context: PerformanceAdjustmentContext): boolean;
269
282
  }
270
283
  /**
271
284
  * Budget controls applied to a gpu-worker job type.
@@ -626,4 +639,4 @@ declare function createWorkerJobBudgetManifestGraph(manifest: WorkerJobBudgetMan
626
639
  */
627
640
  declare function createWorkerJobBudgetAdaptersFromManifest(manifest: WorkerJobBudgetManifest | readonly WorkerJobBudgetManifestJob[], options?: WorkerJobBudgetManifestAdapterOptions): readonly WorkerJobBudgetAdapter[];
628
641
 
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 };
642
+ 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,38 @@ 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 lastTimes = new Array(levelCount);
366
+ const recoveryRatios = new Array(levelCount);
367
+ let pending;
368
+ return {
369
+ record(index, frameTimeMs) {
370
+ const value = readNonNegativeNumber("frameTimeMs", frameTimeMs);
371
+ if (value === void 0) throw new Error("frameTimeMs is required.");
372
+ if (!enabled || value === 0) return;
373
+ lastTimes[index] = value;
374
+ if (pending?.index === index) {
375
+ recoveryRatios[index] = pending.upperTime / value;
376
+ pending = void 0;
377
+ }
378
+ },
379
+ reduced(from, to) {
380
+ const upperTime = lastTimes[from];
381
+ pending = enabled && upperTime !== void 0 ? { index: to, upperTime } : void 0;
382
+ },
383
+ canRecover(index, context) {
384
+ const ratio = recoveryRatios[index];
385
+ return !enabled || ratio === void 0 || context.metrics.latestFrameTimeMs * ratio <= context.target.targetFrameTimeMs * headroom;
386
+ }
387
+ };
388
+ }
389
+
354
390
  // src/ladder.ts
355
391
  function resolveLevelIndex(levels, initialLevel) {
356
392
  if (typeof initialLevel === "number") {
@@ -430,6 +466,7 @@ function createQualityLadderAdapter(options) {
430
466
  const levels = [...options.levels];
431
467
  const metadata = normalizePerformanceBudgetMetadata("budget metadata", options);
432
468
  let currentLevelIndex = resolveLevelIndex(levels, options.initialLevel);
469
+ const recovery = createMeasuredQualityRecovery(levels.length, options.recoveryBudget);
433
470
  const emitChange = (context, adjustment, previousLevelIndex) => {
434
471
  if (typeof options.onLevelChange !== "function") {
435
472
  return;
@@ -450,7 +487,9 @@ function createQualityLadderAdapter(options) {
450
487
  return null;
451
488
  }
452
489
  const previousLevelIndex = currentLevelIndex;
490
+ if (direction === "up" && !recovery.canRecover(currentLevelIndex, context)) return null;
453
491
  currentLevelIndex = nextLevelIndex;
492
+ if (direction === "down") recovery.reduced(previousLevelIndex, currentLevelIndex);
454
493
  const adjustment = buildAdjustment(
455
494
  direction,
456
495
  id,
@@ -476,6 +515,12 @@ function createQualityLadderAdapter(options) {
476
515
  getCurrentLevel() {
477
516
  return levels[currentLevelIndex];
478
517
  },
518
+ recordFrameTime(frameTimeMs) {
519
+ recovery.record(currentLevelIndex, frameTimeMs);
520
+ },
521
+ canStepUp(context) {
522
+ return recovery.canRecover(currentLevelIndex, context);
523
+ },
479
524
  getSnapshot() {
480
525
  return buildSnapshot(
481
526
  id,
@@ -975,7 +1020,8 @@ function createGpuPerformanceGovernor(options) {
975
1020
  supportedFrameRates: options.target?.supportedFrameRates ?? device.supportedFrameRates,
976
1021
  preferredFrameRates: options.target?.preferredFrameRates,
977
1022
  minimumFrameRate: options.target?.minimumFrameRate,
978
- maximumFrameRate: options.target?.maximumFrameRate
1023
+ maximumFrameRate: options.target?.maximumFrameRate,
1024
+ frameBudgetRatio: options.target?.frameBudgetRatio
979
1025
  });
980
1026
  const modules = /* @__PURE__ */ new Map();
981
1027
  if ((options.modules?.length ?? 0) > MAX_MODULE_COUNT) {
@@ -1165,25 +1211,26 @@ function createGpuPerformanceGovernor(options) {
1165
1211
  };
1166
1212
  const attemptRecovery = (metrics, workerGraph, decisionErrors, correlationId) => {
1167
1213
  const context = createContext("recover", "recovering", metrics, workerGraph);
1168
- while (recoveryStack.length > 0) {
1169
- const moduleId = recoveryStack[recoveryStack.length - 1];
1214
+ for (let index = recoveryStack.length - 1; index >= 0; index -= 1) {
1215
+ const moduleId = recoveryStack[index];
1170
1216
  if (!moduleId) {
1171
- recoveryStack.pop();
1217
+ recoveryStack.splice(index, 1);
1172
1218
  continue;
1173
1219
  }
1174
1220
  const module = modules.get(moduleId);
1175
1221
  if (!module) {
1176
- recoveryStack.pop();
1222
+ recoveryStack.splice(index, 1);
1177
1223
  continue;
1178
1224
  }
1179
1225
  try {
1226
+ if (module.canStepUp?.(context) === false) continue;
1180
1227
  const adjustment = module.stepUp(context);
1181
- recoveryStack.pop();
1228
+ recoveryStack.splice(index, 1);
1182
1229
  if (adjustment) {
1183
1230
  return [adjustment];
1184
1231
  }
1185
1232
  } catch {
1186
- recoveryStack.pop();
1233
+ recoveryStack.splice(index, 1);
1187
1234
  appendError(
1188
1235
  createErrorRecord({
1189
1236
  cycle,