@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/CHANGELOG.md
CHANGED
|
@@ -20,6 +20,36 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
|
|
|
20
20
|
- **Security**
|
|
21
21
|
- (placeholder)
|
|
22
22
|
|
|
23
|
+
## [0.1.16] - 2026-11-16
|
|
24
|
+
|
|
25
|
+
- **Added**
|
|
26
|
+
- Opt-in recovery from conservative initial quality levels, with host-provided adjacent cost ratios for unmeasured upgrades.
|
|
27
|
+
|
|
28
|
+
- **Changed**
|
|
29
|
+
- (placeholder)
|
|
30
|
+
|
|
31
|
+
- **Fixed**
|
|
32
|
+
- (placeholder)
|
|
33
|
+
|
|
34
|
+
- **Security**
|
|
35
|
+
- (placeholder)
|
|
36
|
+
|
|
37
|
+
## [0.1.15] - 2026-11-05
|
|
38
|
+
|
|
39
|
+
- **Added**
|
|
40
|
+
- Opt-in measured quality recovery, completed-frame cost recording and retryable adapter recovery admission.
|
|
41
|
+
- Optional frame-budget headroom for earlier adaptation under changing workloads, preserving the negotiated cadence and default thresholds.
|
|
42
|
+
|
|
43
|
+
- **Changed**
|
|
44
|
+
- Refreshed compatible @plasius/* lockfile resolutions to the latest published releases.
|
|
45
|
+
- (placeholder)
|
|
46
|
+
|
|
47
|
+
- **Fixed**
|
|
48
|
+
- (placeholder)
|
|
49
|
+
|
|
50
|
+
- **Security**
|
|
51
|
+
- Resolve demonstrated build/test advisories in Vitest, Vite, glob matching, brace expansion and source-map parsing; production dependencies remain unchanged.
|
|
52
|
+
|
|
23
53
|
## [0.1.14] - 2026-08-31
|
|
24
54
|
|
|
25
55
|
- **Added**
|
|
@@ -312,3 +342,5 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
|
|
|
312
342
|
[0.1.12]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.12
|
|
313
343
|
[0.1.13]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.13
|
|
314
344
|
[0.1.14]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.14
|
|
345
|
+
[0.1.15]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.15
|
|
346
|
+
[0.1.16]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.16
|
package/README.md
CHANGED
|
@@ -144,6 +144,58 @@ for (const [index, frameTimeMs] of [12.8, 13.1, 18.4, 18.9, 19.2, 18.8, 18.1, 17
|
|
|
144
144
|
}
|
|
145
145
|
```
|
|
146
146
|
|
|
147
|
+
For a ladder whose quality levels have measured frame costs, opt into recovery
|
|
148
|
+
admission to avoid repeatedly retrying an over-budget level:
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
const quality = createQualityLadderAdapter({
|
|
152
|
+
id: "interactive-quality",
|
|
153
|
+
domain: "resolution",
|
|
154
|
+
levels: [
|
|
155
|
+
{ id: "preview", config: { scale: 0.5 } },
|
|
156
|
+
{ id: "full", config: { scale: 1 } },
|
|
157
|
+
],
|
|
158
|
+
recoveryBudget: { headroomRatio: 0.9 },
|
|
159
|
+
});
|
|
160
|
+
// Register quality with your governor. After each awaited frame, record its
|
|
161
|
+
// execution duration before governor.recordFrame({ frameTimeMs }).
|
|
162
|
+
quality.recordFrameTime(30);
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
The adapter pairs timings across downgrades, then admits a known higher level
|
|
166
|
+
when its projected cost fits the chosen fraction of the negotiated frame budget.
|
|
167
|
+
Unknown levels can still be explored. Faster execution reopens recovery without
|
|
168
|
+
changing the product's target. Recreate the adapter when the workload or device
|
|
169
|
+
changes. Keep input queue age separate from frame execution time. Cost estimates
|
|
170
|
+
cannot guarantee a deadline when even minimum work exceeds the device budget.
|
|
171
|
+
Custom adapters may implement `canStepUp(context)`; refusal retains pending
|
|
172
|
+
recovery and lets other eligible modules recover. Without this option or hook,
|
|
173
|
+
existing recovery behaviour remains unchanged.
|
|
174
|
+
|
|
175
|
+
For latency-sensitive startup, select a conservative `initialLevel` and set
|
|
176
|
+
`recoverInitialLevels: true` on the governor. This opt-in adds pending recovery
|
|
177
|
+
for registered modules without inventing frame samples. Normal cooldowns,
|
|
178
|
+
measured admission, thermal pressure and authoritative-system protection still
|
|
179
|
+
apply. Historical downgrades recover first. Removing a module removes its pending
|
|
180
|
+
startup recovery; resetting the governor starts admission again from its current
|
|
181
|
+
level. The default remains recovery of governor-issued downgrades only.
|
|
182
|
+
|
|
183
|
+
Set `recoveryBudget.initialCostRatios` to one positive finite cost ratio per
|
|
184
|
+
adjacent upward step when the host can estimate unmeasured work. For example,
|
|
185
|
+
scales 0.5 and 1 at equal samples use `[4]`, while 1 and 2 SPP at equal scale use
|
|
186
|
+
`[2]`. Ratios are copied and constrain the first upgrade; paired completed-frame
|
|
187
|
+
measurements replace them after a downgrade. They are estimates, not guaranteed
|
|
188
|
+
frame times. Engine improvements automatically reopen admission through measured
|
|
189
|
+
execution times, without changing the host's frame-rate target.
|
|
190
|
+
|
|
191
|
+
Hosts can reserve execution headroom without changing their cadence target using
|
|
192
|
+
`target.frameBudgetRatio` (greater than zero and at most one). For a negotiated
|
|
193
|
+
24 FPS target, `0.9` starts reduction above 37.5 ms and admits recovery below
|
|
194
|
+
34.5 ms. Omit it to retain the existing thresholds. Supply the supported/preferred
|
|
195
|
+
frame-rate buckets for a non-default cadence. Shorter existing sample windows and
|
|
196
|
+
cooldowns let rapidly changing camera workloads respond earlier; they remain host
|
|
197
|
+
policy. Keep the ladder's recovery reserve consistent with this execution reserve.
|
|
198
|
+
|
|
147
199
|
Ray-tracing-first budget metadata is part of the public contract:
|
|
148
200
|
|
|
149
201
|
- `representationBands`: `near`, `mid`, `far`, `horizon`
|
package/dist/index.cjs
CHANGED
|
@@ -209,6 +209,10 @@ function createDeviceProfile(input = {}) {
|
|
|
209
209
|
});
|
|
210
210
|
}
|
|
211
211
|
function negotiateFrameTarget(options = {}) {
|
|
212
|
+
const frameBudgetRatio = readPositiveNumber("frameBudgetRatio", options.frameBudgetRatio);
|
|
213
|
+
if (frameBudgetRatio !== void 0 && frameBudgetRatio > 1) {
|
|
214
|
+
throw new Error("frameBudgetRatio must be at most one.");
|
|
215
|
+
}
|
|
212
216
|
const mode = options.mode === void 0 ? "flat" : assertEnumValue("mode", options.mode, runtimeModes);
|
|
213
217
|
const minimumFrameRate = Math.round(
|
|
214
218
|
readPositiveNumber("minimumFrameRate", options.minimumFrameRate) ?? 60
|
|
@@ -265,8 +269,8 @@ function negotiateFrameTarget(options = {}) {
|
|
|
265
269
|
rationale.push("Immersive modes prefer headset-native cadence when the session supports it.");
|
|
266
270
|
}
|
|
267
271
|
const targetFrameTimeMs = 1e3 / targetFrameRate;
|
|
268
|
-
const downgradeMultiplier = mode === "flat" ? 1.05 : 1.03;
|
|
269
|
-
const upgradeMultiplier = mode === "flat" ? 0.92 : 0.95;
|
|
272
|
+
const downgradeMultiplier = frameBudgetRatio ?? (mode === "flat" ? 1.05 : 1.03);
|
|
273
|
+
const upgradeMultiplier = (frameBudgetRatio ?? 1) * (mode === "flat" ? 0.92 : 0.95);
|
|
270
274
|
return Object.freeze({
|
|
271
275
|
mode,
|
|
272
276
|
minimumFrameRate,
|
|
@@ -394,6 +398,42 @@ function normalizePerformanceBudgetMetadata(name, value) {
|
|
|
394
398
|
});
|
|
395
399
|
}
|
|
396
400
|
|
|
401
|
+
// src/quality-recovery.ts
|
|
402
|
+
function createMeasuredQualityRecovery(levelCount, options) {
|
|
403
|
+
const enabled = options !== void 0;
|
|
404
|
+
const headroom = enabled ? readPositiveNumber("recoveryBudget.headroomRatio", options?.headroomRatio) : 1;
|
|
405
|
+
if (headroom === void 0 || headroom > 1) {
|
|
406
|
+
throw new Error("recoveryBudget.headroomRatio must be in (0, 1].");
|
|
407
|
+
}
|
|
408
|
+
const initialRatios = options?.initialCostRatios;
|
|
409
|
+
if (initialRatios !== void 0 && (!Array.isArray(initialRatios) || initialRatios.length !== levelCount - 1 || Array.from(initialRatios).some((value) => typeof value !== "number" || !Number.isFinite(value) || value <= 0))) {
|
|
410
|
+
throw new Error("recoveryBudget.initialCostRatios must contain one finite positive ratio per upward step.");
|
|
411
|
+
}
|
|
412
|
+
const lastTimes = new Array(levelCount);
|
|
413
|
+
const recoveryRatios = initialRatios ? [...initialRatios] : new Array(levelCount);
|
|
414
|
+
let pending;
|
|
415
|
+
return {
|
|
416
|
+
record(index, frameTimeMs) {
|
|
417
|
+
const value = readNonNegativeNumber("frameTimeMs", frameTimeMs);
|
|
418
|
+
if (value === void 0) throw new Error("frameTimeMs is required.");
|
|
419
|
+
if (!enabled || value === 0) return;
|
|
420
|
+
lastTimes[index] = value;
|
|
421
|
+
if (pending?.index === index) {
|
|
422
|
+
recoveryRatios[index] = pending.upperTime / value;
|
|
423
|
+
pending = void 0;
|
|
424
|
+
}
|
|
425
|
+
},
|
|
426
|
+
reduced(from, to) {
|
|
427
|
+
const upperTime = lastTimes[from];
|
|
428
|
+
pending = enabled && upperTime !== void 0 ? { index: to, upperTime } : void 0;
|
|
429
|
+
},
|
|
430
|
+
canRecover(index, context) {
|
|
431
|
+
const ratio = recoveryRatios[index];
|
|
432
|
+
return !enabled || ratio === void 0 || context.metrics.latestFrameTimeMs * ratio <= context.target.targetFrameTimeMs * headroom;
|
|
433
|
+
}
|
|
434
|
+
};
|
|
435
|
+
}
|
|
436
|
+
|
|
397
437
|
// src/ladder.ts
|
|
398
438
|
function resolveLevelIndex(levels, initialLevel) {
|
|
399
439
|
if (typeof initialLevel === "number") {
|
|
@@ -473,6 +513,7 @@ function createQualityLadderAdapter(options) {
|
|
|
473
513
|
const levels = [...options.levels];
|
|
474
514
|
const metadata = normalizePerformanceBudgetMetadata("budget metadata", options);
|
|
475
515
|
let currentLevelIndex = resolveLevelIndex(levels, options.initialLevel);
|
|
516
|
+
const recovery = createMeasuredQualityRecovery(levels.length, options.recoveryBudget);
|
|
476
517
|
const emitChange = (context, adjustment, previousLevelIndex) => {
|
|
477
518
|
if (typeof options.onLevelChange !== "function") {
|
|
478
519
|
return;
|
|
@@ -493,7 +534,9 @@ function createQualityLadderAdapter(options) {
|
|
|
493
534
|
return null;
|
|
494
535
|
}
|
|
495
536
|
const previousLevelIndex = currentLevelIndex;
|
|
537
|
+
if (direction === "up" && !recovery.canRecover(currentLevelIndex, context)) return null;
|
|
496
538
|
currentLevelIndex = nextLevelIndex;
|
|
539
|
+
if (direction === "down") recovery.reduced(previousLevelIndex, currentLevelIndex);
|
|
497
540
|
const adjustment = buildAdjustment(
|
|
498
541
|
direction,
|
|
499
542
|
id,
|
|
@@ -519,6 +562,12 @@ function createQualityLadderAdapter(options) {
|
|
|
519
562
|
getCurrentLevel() {
|
|
520
563
|
return levels[currentLevelIndex];
|
|
521
564
|
},
|
|
565
|
+
recordFrameTime(frameTimeMs) {
|
|
566
|
+
recovery.record(currentLevelIndex, frameTimeMs);
|
|
567
|
+
},
|
|
568
|
+
canStepUp(context) {
|
|
569
|
+
return recovery.canRecover(currentLevelIndex, context);
|
|
570
|
+
},
|
|
522
571
|
getSnapshot() {
|
|
523
572
|
return buildSnapshot(
|
|
524
573
|
id,
|
|
@@ -1005,6 +1054,9 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1005
1054
|
throw new Error("createGpuPerformanceGovernor requires an options object.");
|
|
1006
1055
|
}
|
|
1007
1056
|
validateTelemetryHooks(options.telemetry);
|
|
1057
|
+
if (options.recoverInitialLevels !== void 0 && typeof options.recoverInitialLevels !== "boolean") {
|
|
1058
|
+
throw new Error("recoverInitialLevels must be a boolean.");
|
|
1059
|
+
}
|
|
1008
1060
|
const device = createDeviceProfile(options.device);
|
|
1009
1061
|
if (!device.supportsWebGpu) {
|
|
1010
1062
|
throw new Error(
|
|
@@ -1018,7 +1070,8 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1018
1070
|
supportedFrameRates: options.target?.supportedFrameRates ?? device.supportedFrameRates,
|
|
1019
1071
|
preferredFrameRates: options.target?.preferredFrameRates,
|
|
1020
1072
|
minimumFrameRate: options.target?.minimumFrameRate,
|
|
1021
|
-
maximumFrameRate: options.target?.maximumFrameRate
|
|
1073
|
+
maximumFrameRate: options.target?.maximumFrameRate,
|
|
1074
|
+
frameBudgetRatio: options.target?.frameBudgetRatio
|
|
1022
1075
|
});
|
|
1023
1076
|
const modules = /* @__PURE__ */ new Map();
|
|
1024
1077
|
if ((options.modules?.length ?? 0) > MAX_MODULE_COUNT) {
|
|
@@ -1040,6 +1093,7 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1040
1093
|
let lastDownCycle = Number.NEGATIVE_INFINITY;
|
|
1041
1094
|
let lastUpCycle = Number.NEGATIVE_INFINITY;
|
|
1042
1095
|
let recoveryStack = [];
|
|
1096
|
+
const initialRecovery = new Set(options.recoverInitialLevels ? modules.keys() : []);
|
|
1043
1097
|
let recentErrors = [];
|
|
1044
1098
|
let recentFrameIds = /* @__PURE__ */ new Set();
|
|
1045
1099
|
let recentFrameIdQueue = [];
|
|
@@ -1208,25 +1262,41 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1208
1262
|
};
|
|
1209
1263
|
const attemptRecovery = (metrics, workerGraph, decisionErrors, correlationId) => {
|
|
1210
1264
|
const context = createContext("recover", "recovering", metrics, workerGraph);
|
|
1211
|
-
|
|
1212
|
-
|
|
1265
|
+
const pending = recoveryStack.map((moduleId, index) => ({ moduleId, index })).reverse();
|
|
1266
|
+
const reduced = new Set(recoveryStack);
|
|
1267
|
+
for (const moduleId of initialRecovery) {
|
|
1268
|
+
if (!reduced.has(moduleId)) pending.push({ moduleId, index: -1 });
|
|
1269
|
+
}
|
|
1270
|
+
for (const { moduleId, index } of pending) {
|
|
1271
|
+
const remove = () => {
|
|
1272
|
+
if (index >= 0) recoveryStack.splice(index, 1);
|
|
1273
|
+
else initialRecovery.delete(moduleId);
|
|
1274
|
+
};
|
|
1213
1275
|
if (!moduleId) {
|
|
1214
|
-
|
|
1276
|
+
remove();
|
|
1215
1277
|
continue;
|
|
1216
1278
|
}
|
|
1217
1279
|
const module2 = modules.get(moduleId);
|
|
1218
1280
|
if (!module2) {
|
|
1219
|
-
|
|
1281
|
+
remove();
|
|
1220
1282
|
continue;
|
|
1221
1283
|
}
|
|
1222
1284
|
try {
|
|
1285
|
+
if (index < 0) {
|
|
1286
|
+
const snapshot = module2.getSnapshot();
|
|
1287
|
+
if (snapshot.isAtMaximum || snapshot.authority === "authoritative" && !adaptation.allowAuthoritativeScaling) {
|
|
1288
|
+
remove();
|
|
1289
|
+
continue;
|
|
1290
|
+
}
|
|
1291
|
+
}
|
|
1292
|
+
if (module2.canStepUp?.(context) === false) continue;
|
|
1223
1293
|
const adjustment = module2.stepUp(context);
|
|
1224
|
-
|
|
1294
|
+
if (index >= 0 || !adjustment) remove();
|
|
1225
1295
|
if (adjustment) {
|
|
1226
1296
|
return [adjustment];
|
|
1227
1297
|
}
|
|
1228
1298
|
} catch {
|
|
1229
|
-
|
|
1299
|
+
remove();
|
|
1230
1300
|
appendError(
|
|
1231
1301
|
createErrorRecord({
|
|
1232
1302
|
cycle,
|
|
@@ -1338,9 +1408,11 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1338
1408
|
throw new Error(`Module "${module2.id}" is already registered.`);
|
|
1339
1409
|
}
|
|
1340
1410
|
modules.set(module2.id, module2);
|
|
1411
|
+
if (options.recoverInitialLevels) initialRecovery.add(module2.id);
|
|
1341
1412
|
return () => {
|
|
1342
1413
|
modules.delete(module2.id);
|
|
1343
1414
|
recoveryStack = recoveryStack.filter((id) => id !== module2.id);
|
|
1415
|
+
initialRecovery.delete(module2.id);
|
|
1344
1416
|
};
|
|
1345
1417
|
},
|
|
1346
1418
|
getTarget() {
|
|
@@ -1369,6 +1441,8 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1369
1441
|
lastDownCycle = Number.NEGATIVE_INFINITY;
|
|
1370
1442
|
lastUpCycle = Number.NEGATIVE_INFINITY;
|
|
1371
1443
|
recoveryStack = [];
|
|
1444
|
+
initialRecovery.clear();
|
|
1445
|
+
if (options.recoverInitialLevels) for (const id of modules.keys()) initialRecovery.add(id);
|
|
1372
1446
|
recentErrors = [];
|
|
1373
1447
|
recentFrameIds = /* @__PURE__ */ new Set();
|
|
1374
1448
|
recentFrameIdQueue = [];
|