@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/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 ("mid" | "near" | "far" | "horizon")[];
603
- declare const rayTracingQualityDimensions: readonly ("shadows" | "geometry" | "animation" | "deformation" | "shading" | "rayTracing" | "lightingSamples" | "updateCadence" | "temporalReuse")[];
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 { 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 };
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 ("mid" | "near" | "far" | "horizon")[];
603
- declare const rayTracingQualityDimensions: readonly ("shadows" | "geometry" | "animation" | "deformation" | "shading" | "rayTracing" | "lightingSamples" | "updateCadence" | "temporalReuse")[];
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 { 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 };
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
- for (let index = recoveryStack.length - 1; index >= 0; index -= 1) {
1215
- const moduleId = recoveryStack[index];
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
- recoveryStack.splice(index, 1);
1233
+ remove();
1218
1234
  continue;
1219
1235
  }
1220
1236
  const module = modules.get(moduleId);
1221
1237
  if (!module) {
1222
- recoveryStack.splice(index, 1);
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
- recoveryStack.splice(index, 1);
1251
+ if (index >= 0 || !adjustment) remove();
1229
1252
  if (adjustment) {
1230
1253
  return [adjustment];
1231
1254
  }
1232
1255
  } catch {
1233
- recoveryStack.splice(index, 1);
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 = [];