@plasius/gpu-performance 0.1.14 → 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/CHANGELOG.md +17 -0
- package/README.md +36 -0
- package/dist/index.cjs +56 -9
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +14 -1
- package/dist/index.d.ts +14 -1
- package/dist/index.js +56 -9
- package/dist/index.js.map +1 -1
- package/package.json +9 -6
package/CHANGELOG.md
CHANGED
|
@@ -20,6 +20,22 @@ 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.15] - 2026-11-05
|
|
24
|
+
|
|
25
|
+
- **Added**
|
|
26
|
+
- Opt-in measured quality recovery, completed-frame cost recording and retryable adapter recovery admission.
|
|
27
|
+
- Optional frame-budget headroom for earlier adaptation under changing workloads, preserving the negotiated cadence and default thresholds.
|
|
28
|
+
|
|
29
|
+
- **Changed**
|
|
30
|
+
- Refreshed compatible @plasius/* lockfile resolutions to the latest published releases.
|
|
31
|
+
- (placeholder)
|
|
32
|
+
|
|
33
|
+
- **Fixed**
|
|
34
|
+
- (placeholder)
|
|
35
|
+
|
|
36
|
+
- **Security**
|
|
37
|
+
- Resolve demonstrated build/test advisories in Vitest, Vite, glob matching, brace expansion and source-map parsing; production dependencies remain unchanged.
|
|
38
|
+
|
|
23
39
|
## [0.1.14] - 2026-08-31
|
|
24
40
|
|
|
25
41
|
- **Added**
|
|
@@ -312,3 +328,4 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
|
|
|
312
328
|
[0.1.12]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.12
|
|
313
329
|
[0.1.13]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.13
|
|
314
330
|
[0.1.14]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.14
|
|
331
|
+
[0.1.15]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.15
|
package/README.md
CHANGED
|
@@ -144,6 +144,42 @@ 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
|
+
Hosts can reserve execution headroom without changing their cadence target using
|
|
176
|
+
`target.frameBudgetRatio` (greater than zero and at most one). For a negotiated
|
|
177
|
+
24 FPS target, `0.9` starts reduction above 37.5 ms and admits recovery below
|
|
178
|
+
34.5 ms. Omit it to retain the existing thresholds. Supply the supported/preferred
|
|
179
|
+
frame-rate buckets for a non-default cadence. Shorter existing sample windows and
|
|
180
|
+
cooldowns let rapidly changing camera workloads respond earlier; they remain host
|
|
181
|
+
policy. Keep the ladder's recovery reserve consistent with this execution reserve.
|
|
182
|
+
|
|
147
183
|
Ray-tracing-first budget metadata is part of the public contract:
|
|
148
184
|
|
|
149
185
|
- `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,38 @@ 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 lastTimes = new Array(levelCount);
|
|
409
|
+
const recoveryRatios = new Array(levelCount);
|
|
410
|
+
let pending;
|
|
411
|
+
return {
|
|
412
|
+
record(index, frameTimeMs) {
|
|
413
|
+
const value = readNonNegativeNumber("frameTimeMs", frameTimeMs);
|
|
414
|
+
if (value === void 0) throw new Error("frameTimeMs is required.");
|
|
415
|
+
if (!enabled || value === 0) return;
|
|
416
|
+
lastTimes[index] = value;
|
|
417
|
+
if (pending?.index === index) {
|
|
418
|
+
recoveryRatios[index] = pending.upperTime / value;
|
|
419
|
+
pending = void 0;
|
|
420
|
+
}
|
|
421
|
+
},
|
|
422
|
+
reduced(from, to) {
|
|
423
|
+
const upperTime = lastTimes[from];
|
|
424
|
+
pending = enabled && upperTime !== void 0 ? { index: to, upperTime } : void 0;
|
|
425
|
+
},
|
|
426
|
+
canRecover(index, context) {
|
|
427
|
+
const ratio = recoveryRatios[index];
|
|
428
|
+
return !enabled || ratio === void 0 || context.metrics.latestFrameTimeMs * ratio <= context.target.targetFrameTimeMs * headroom;
|
|
429
|
+
}
|
|
430
|
+
};
|
|
431
|
+
}
|
|
432
|
+
|
|
397
433
|
// src/ladder.ts
|
|
398
434
|
function resolveLevelIndex(levels, initialLevel) {
|
|
399
435
|
if (typeof initialLevel === "number") {
|
|
@@ -473,6 +509,7 @@ function createQualityLadderAdapter(options) {
|
|
|
473
509
|
const levels = [...options.levels];
|
|
474
510
|
const metadata = normalizePerformanceBudgetMetadata("budget metadata", options);
|
|
475
511
|
let currentLevelIndex = resolveLevelIndex(levels, options.initialLevel);
|
|
512
|
+
const recovery = createMeasuredQualityRecovery(levels.length, options.recoveryBudget);
|
|
476
513
|
const emitChange = (context, adjustment, previousLevelIndex) => {
|
|
477
514
|
if (typeof options.onLevelChange !== "function") {
|
|
478
515
|
return;
|
|
@@ -493,7 +530,9 @@ function createQualityLadderAdapter(options) {
|
|
|
493
530
|
return null;
|
|
494
531
|
}
|
|
495
532
|
const previousLevelIndex = currentLevelIndex;
|
|
533
|
+
if (direction === "up" && !recovery.canRecover(currentLevelIndex, context)) return null;
|
|
496
534
|
currentLevelIndex = nextLevelIndex;
|
|
535
|
+
if (direction === "down") recovery.reduced(previousLevelIndex, currentLevelIndex);
|
|
497
536
|
const adjustment = buildAdjustment(
|
|
498
537
|
direction,
|
|
499
538
|
id,
|
|
@@ -519,6 +558,12 @@ function createQualityLadderAdapter(options) {
|
|
|
519
558
|
getCurrentLevel() {
|
|
520
559
|
return levels[currentLevelIndex];
|
|
521
560
|
},
|
|
561
|
+
recordFrameTime(frameTimeMs) {
|
|
562
|
+
recovery.record(currentLevelIndex, frameTimeMs);
|
|
563
|
+
},
|
|
564
|
+
canStepUp(context) {
|
|
565
|
+
return recovery.canRecover(currentLevelIndex, context);
|
|
566
|
+
},
|
|
522
567
|
getSnapshot() {
|
|
523
568
|
return buildSnapshot(
|
|
524
569
|
id,
|
|
@@ -1018,7 +1063,8 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1018
1063
|
supportedFrameRates: options.target?.supportedFrameRates ?? device.supportedFrameRates,
|
|
1019
1064
|
preferredFrameRates: options.target?.preferredFrameRates,
|
|
1020
1065
|
minimumFrameRate: options.target?.minimumFrameRate,
|
|
1021
|
-
maximumFrameRate: options.target?.maximumFrameRate
|
|
1066
|
+
maximumFrameRate: options.target?.maximumFrameRate,
|
|
1067
|
+
frameBudgetRatio: options.target?.frameBudgetRatio
|
|
1022
1068
|
});
|
|
1023
1069
|
const modules = /* @__PURE__ */ new Map();
|
|
1024
1070
|
if ((options.modules?.length ?? 0) > MAX_MODULE_COUNT) {
|
|
@@ -1208,25 +1254,26 @@ function createGpuPerformanceGovernor(options) {
|
|
|
1208
1254
|
};
|
|
1209
1255
|
const attemptRecovery = (metrics, workerGraph, decisionErrors, correlationId) => {
|
|
1210
1256
|
const context = createContext("recover", "recovering", metrics, workerGraph);
|
|
1211
|
-
|
|
1212
|
-
const moduleId = recoveryStack[
|
|
1257
|
+
for (let index = recoveryStack.length - 1; index >= 0; index -= 1) {
|
|
1258
|
+
const moduleId = recoveryStack[index];
|
|
1213
1259
|
if (!moduleId) {
|
|
1214
|
-
recoveryStack.
|
|
1260
|
+
recoveryStack.splice(index, 1);
|
|
1215
1261
|
continue;
|
|
1216
1262
|
}
|
|
1217
1263
|
const module2 = modules.get(moduleId);
|
|
1218
1264
|
if (!module2) {
|
|
1219
|
-
recoveryStack.
|
|
1265
|
+
recoveryStack.splice(index, 1);
|
|
1220
1266
|
continue;
|
|
1221
1267
|
}
|
|
1222
1268
|
try {
|
|
1269
|
+
if (module2.canStepUp?.(context) === false) continue;
|
|
1223
1270
|
const adjustment = module2.stepUp(context);
|
|
1224
|
-
recoveryStack.
|
|
1271
|
+
recoveryStack.splice(index, 1);
|
|
1225
1272
|
if (adjustment) {
|
|
1226
1273
|
return [adjustment];
|
|
1227
1274
|
}
|
|
1228
1275
|
} catch {
|
|
1229
|
-
recoveryStack.
|
|
1276
|
+
recoveryStack.splice(index, 1);
|
|
1230
1277
|
appendError(
|
|
1231
1278
|
createErrorRecord({
|
|
1232
1279
|
cycle,
|