@threenative/core 0.3.3 → 0.3.5
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/capabilities.json +2019 -59
- package/dist/{assets-CYKk2WTu.d.ts → assets-CqvE429w.d.ts} +45 -3
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-C1SnMoJ-.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-D_6r-k4Y.d.ts → game-Bj8G1wmD.d.ts} +242 -17
- package/dist/hot.d.ts +5 -5
- package/dist/index.d.ts +1131 -105
- package/dist/index.js +15201 -4782
- package/dist/model-lod-BDAUYgsS.d.ts +197 -0
- package/dist/playtest.d.ts +6 -4
- package/dist/playtest.js +84 -11
- package/dist/react-css.d.ts +62 -0
- package/dist/react-css.js +591 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-Cy4qeBOA.d.ts → renderer-9yEo9hPa.d.ts} +676 -21
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.d.ts +5 -3
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +1596 -17
- package/dist/world.js +17035 -521
- package/gpl/fixtures/make_world_fixture.py +184 -0
- package/gpl/recipes/_common.py +11 -0
- package/gpl/recipes/decimate.py +11 -5
- package/gpl/recipes/export_world.py +699 -0
- package/mcp/blender-server.mjs +61 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +55 -21
- package/mcp/servers.mjs +4 -4
- package/package.json +15 -9
- package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
- package/patches/three@0.185.1.patch +8246 -389
- package/scripts/apply-three-patch.mjs +123 -41
- package/src/animation-blend.ts +264 -0
- package/src/animation-composition.ts +362 -0
- package/src/animation-layers.ts +260 -0
- package/src/animation-root-motion.ts +283 -0
- package/src/animation.ts +896 -0
- package/src/assets.ts +1303 -0
- package/src/atmosphere/index.ts +335 -0
- package/src/atmosphere/luts.ts +298 -0
- package/src/atmosphere/params.ts +323 -0
- package/src/audio.ts +912 -0
- package/src/billboard.ts +124 -0
- package/src/bone-lengths.ts +157 -0
- package/src/camera-shake.ts +116 -0
- package/src/canvas-layer.ts +47 -0
- package/src/clip-audit.ts +401 -0
- package/src/clustered-batch.ts +492 -0
- package/src/clustered-mesh.ts +638 -0
- package/src/compute-driven.ts +176 -0
- package/src/compute-timing.ts +318 -0
- package/src/config.ts +593 -0
- package/src/debug.ts +82 -0
- package/src/engine-render-hook.ts +25 -0
- package/src/entities.ts +79 -0
- package/src/entity-snapshot.ts +53 -0
- package/src/flight.ts +683 -0
- package/src/fluid-field.ts +748 -0
- package/src/fluid-particles.ts +1253 -0
- package/src/frame-budget.ts +1368 -0
- package/src/game.ts +2390 -0
- package/src/geometry-capture.ts +1098 -0
- package/src/gpu-class.ts +160 -0
- package/src/gpu-frame-observation.ts +424 -0
- package/src/gpu-readback.ts +143 -0
- package/src/gpu-scene-bvh.ts +464 -0
- package/src/grounding.ts +100 -0
- package/src/hot.ts +161 -0
- package/src/import-meta.d.ts +13 -0
- package/src/index.ts +1536 -0
- package/src/input.ts +690 -0
- package/src/instanced-batch-lod.ts +283 -0
- package/src/instanced-batch.ts +274 -0
- package/src/interpolation.ts +129 -0
- package/src/launch-diagnostics.ts +161 -0
- package/src/loop.ts +564 -0
- package/src/matrix-world.ts +245 -0
- package/src/merge-parts.ts +812 -0
- package/src/model-lod.ts +1315 -0
- package/src/net-protocol.ts +333 -0
- package/src/net-session.ts +477 -0
- package/src/net.ts +80 -0
- package/src/ocean/fft.ts +72 -0
- package/src/ocean/spectral.ts +728 -0
- package/src/particle-significance.ts +102 -0
- package/src/particles.ts +648 -0
- package/src/path-follow.ts +175 -0
- package/src/picking.ts +250 -0
- package/src/pipeline-census.ts +1566 -0
- package/src/platform.ts +210 -0
- package/src/playtest.ts +839 -0
- package/src/pointer-events.ts +411 -0
- package/src/pose-measure.ts +435 -0
- package/src/profiling/FrameCounters.ts +231 -0
- package/src/profiling/Spans.ts +548 -0
- package/src/profiling/opacity-convention.ts +21 -0
- package/src/profiling/render-list-validate.ts +175 -0
- package/src/profiling/render-trap-audit.ts +84 -0
- package/src/profiling/scene-warning.ts +190 -0
- package/src/profiling/span-probes.ts +191 -0
- package/src/profiling/unlit-foliage-warning.ts +149 -0
- package/src/projection-apply.ts +1529 -0
- package/src/projection-marker.ts +142 -0
- package/src/projection-plan.ts +1258 -0
- package/src/projection-skinned.ts +419 -0
- package/src/projection-stability.ts +409 -0
- package/src/projection-uniform.ts +328 -0
- package/src/random.ts +41 -0
- package/src/react-css.ts +604 -0
- package/src/react-glyphs.ts +114 -0
- package/src/react-host.ts +576 -0
- package/src/react-layout.ts +265 -0
- package/src/react.ts +60 -0
- package/src/render/alpha-antialiasing.ts +159 -0
- package/src/render/batched-velocity.ts +126 -0
- package/src/render/chain.ts +1021 -0
- package/src/render/daylight.ts +189 -0
- package/src/render/depth-pyramid.ts +596 -0
- package/src/render/foliage-alpha.ts +166 -0
- package/src/render/material-key.ts +60 -0
- package/src/render/mesh-pool.ts +144 -0
- package/src/render/probe-volume.ts +1668 -0
- package/src/render/resolution-subrect.ts +253 -0
- package/src/render/velocity.ts +442 -0
- package/src/render/virtual-shadow-pages.ts +827 -0
- package/src/render/virtual-shadow-partial.ts +174 -0
- package/src/render/virtual-shadow.ts +3330 -0
- package/src/render/world-impostor-surface.ts +722 -0
- package/src/render/world-impostor.ts +558 -0
- package/src/render-camera-cull.ts +441 -0
- package/src/render-pass-budget.ts +501 -0
- package/src/renderProjection.ts +758 -0
- package/src/renderer-config.ts +127 -0
- package/src/renderer.ts +1847 -0
- package/src/replay-protocol.ts +85 -0
- package/src/replay.ts +205 -0
- package/src/resolution-scaler.ts +819 -0
- package/src/rig-preparation.ts +271 -0
- package/src/ripple-field.ts +432 -0
- package/src/scale.ts +109 -0
- package/src/scene.ts +239 -0
- package/src/schedule.ts +155 -0
- package/src/skeletal-mesh.ts +61 -0
- package/src/skeleton.ts +100 -0
- package/src/snow-field.ts +744 -0
- package/src/softbody-topology.ts +269 -0
- package/src/softbody.ts +516 -0
- package/src/sprite-animator.ts +222 -0
- package/src/startup-readiness.ts +386 -0
- package/src/state.ts +66 -0
- package/src/static-transform.ts +274 -0
- package/src/storage-buffer.ts +253 -0
- package/src/streaming.ts +308 -0
- package/src/target-fps.ts +92 -0
- package/src/terrain-jobs-worker.ts +17 -0
- package/src/terrain-jobs.ts +353 -0
- package/src/textures.ts +39 -0
- package/src/tracers.ts +237 -0
- package/src/ui-bridge.ts +368 -0
- package/src/ui-hit-regions.ts +380 -0
- package/src/ui-layer.ts +83 -0
- package/src/ui-state.ts +220 -0
- package/src/version.ts +2 -0
- package/src/viewport.ts +253 -0
- package/src/warmup.ts +1357 -0
- package/src/water-surface.ts +384 -0
- package/src/wave-field.ts +524 -0
- package/src/world-capabilities.ts +131 -0
- package/src/world-cell-proxy.ts +392 -0
- package/src/world-cells.ts +10564 -0
- package/src/world-gpu-scene.ts +3354 -0
- package/src/world-heightmap.ts +82 -0
- package/src/world-package.ts +469 -0
- package/src/world-passes.ts +582 -0
- package/src/world-region.ts +17 -0
- package/src/world-terrain-splat.ts +564 -0
- package/src/world-tiles.ts +3826 -0
- package/src/world-topology.ts +370 -0
- package/src/world-validate.ts +48 -0
- package/src/world.ts +805 -0
- package/dist/gpu-readback-CMklJs6r.d.ts +0 -112
|
@@ -0,0 +1,819 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The adaptive drawing-buffer scale: PRD-228 Change A's loop.
|
|
3
|
+
*
|
|
4
|
+
* A game reaches its `display.maxFps` target without hand-authoring a resolution constant.
|
|
5
|
+
* Bayview's own constant took an afternoon and three ladder rungs to find on a physical Pixel 8;
|
|
6
|
+
* the next game would have repeated that from scratch, which is what makes the loop framework
|
|
7
|
+
* work rather than game work.
|
|
8
|
+
*
|
|
9
|
+
* Every number below is pre-registered in the PRD before this file existed and is read from one
|
|
10
|
+
* constant block. A controller tuned inside its own implementation until a playtest went green is
|
|
11
|
+
* a controller nobody can argue with afterwards, so the values move by editing the PRD.
|
|
12
|
+
*
|
|
13
|
+
* Nothing here touches the overlay surface, the camera or the aspect ratio: only the 3D drawing
|
|
14
|
+
* buffer moves, which is the arrangement the device ladder measured and accepted.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import type { GpuClass } from "./gpu-class.js";
|
|
18
|
+
|
|
19
|
+
/** How the active scale was arrived at, reported beside every fps number. */
|
|
20
|
+
export type ScaleSource = "pinned" | "auto" | "auto-pinned";
|
|
21
|
+
|
|
22
|
+
export const RESOLUTION_SCALER = {
|
|
23
|
+
/**
|
|
24
|
+
* Ratio 0.85 linear, so each step is 0.72x the pixels. Coarse on purpose: every step
|
|
25
|
+
* reallocates render targets on WebGPU, and fine granularity buys smoothness with hitches.
|
|
26
|
+
*/
|
|
27
|
+
rungs: [1.0, 0.85, 0.72, 0.61, 0.52, 0.44, 0.38, 0.32, 0.27, 0.23] as const,
|
|
28
|
+
/**
|
|
29
|
+
* The lowest rung a desktop may take while nothing in the render chain reconstructs a
|
|
30
|
+
* full-resolution frame from the smaller one.
|
|
31
|
+
*
|
|
32
|
+
* The ladder above is the device arm's, and it ends at 0.23 because a phone buys the pixels back
|
|
33
|
+
* differently. A desktop has nothing: no temporal stage, no reconstruction, just 5% of the
|
|
34
|
+
* pixels stretched across the panel, which is blocky mush rather than a slow frame — and the
|
|
35
|
+
* report at that point claims the budget was met. 0.61 is where surrendering more pixels stops
|
|
36
|
+
* buying frame time worth what it costs to look at, and it is reported as `atFloor` rather than
|
|
37
|
+
* passed in silence. A host whose chain *does* reconstruct the frame says so, and the deep
|
|
38
|
+
* rungs come back; `renderer-config.ts` decides which floor a platform starts with.
|
|
39
|
+
*/
|
|
40
|
+
desktopFloorScale: 0.61,
|
|
41
|
+
/**
|
|
42
|
+
* The rung a class of adapter starts on instead of the ceiling; a class not named here starts at
|
|
43
|
+
* 1.0. Only `mobile-low` moves: one rung down is 0.85, close to the 0.8 content scale Unreal's
|
|
44
|
+
* Low Android bucket sets. A start is a guess the first eligible window corrects — it steps down
|
|
45
|
+
* at once and climbs after `upWindows` clean ones — so a wrong row costs windows, not a stuck
|
|
46
|
+
* look. `unknown` and `discrete` keep the ceiling on purpose: a strong GPU is never capped by a
|
|
47
|
+
* table row.
|
|
48
|
+
*/
|
|
49
|
+
startScaleByGpuClass: { "mobile-low": 0.85 } as Partial<Record<GpuClass, number>>,
|
|
50
|
+
/**
|
|
51
|
+
* The signal is **fps against the configured target**, not the presented interval.
|
|
52
|
+
*
|
|
53
|
+
* Amended 2026-08-28 from a device arm, before the second implementation. The original triggers
|
|
54
|
+
* were `presented p95 > 14 ms` down and `< 11.5 ms` up. Under FIFO the presented interval is the
|
|
55
|
+
* *panel's* period, not the game's cost: a game locked at 60 fps on a 60 Hz panel reports
|
|
56
|
+
* presented p95 around 17.5 ms, so `> 14` is true forever. A scaffolded template holding
|
|
57
|
+
* 59.99 fps with a `frame p95` of 7.99 ms out of 16.67 was walked to 552x248 and then told it
|
|
58
|
+
* had run out of room. fps is correct in both regimes: it comes from the mean presented
|
|
59
|
+
* interval, so dropped frames pull it down on their own, and a missed target is missed whether
|
|
60
|
+
* or not a panel caps the top.
|
|
61
|
+
*/
|
|
62
|
+
targetFpsFraction: 0.98,
|
|
63
|
+
/**
|
|
64
|
+
* The tail guard on the up-step only. A frame that hits its average target while dropping frames
|
|
65
|
+
* has headroom on paper and none in the hand. A vsync-capped panel's own p95 floor sits near
|
|
66
|
+
* 1.05x the budget, comfortably inside this.
|
|
67
|
+
*/
|
|
68
|
+
upTailFraction: 1.15,
|
|
69
|
+
/**
|
|
70
|
+
* A window whose presented p99 is at least this many times its p50 is measuring a **stall**, not
|
|
71
|
+
* a frame rate, and the controller defers on it rather than acting.
|
|
72
|
+
*
|
|
73
|
+
* Amended 2026-08-30 from a browser arm, and this is the second time the fps signal has needed
|
|
74
|
+
* correcting for the same underlying reason: `fps` is `1000 / mean`, and a mean is not robust.
|
|
75
|
+
* `sandbox/lumen-hall` on an NVIDIA Turing at 1600x900 spent its second window building WebGPU
|
|
76
|
+
* pipelines for a five-stage TSL chain. Four of that window's 300 frames took about two seconds
|
|
77
|
+
* each — under `hitchMs`, so they stayed in the window and were averaged. The window reported
|
|
78
|
+
* **22.6 fps** with a **p50 of 9.8 ms**, which is 102 fps. The controller read a 2.6x deficit,
|
|
79
|
+
* took its maximum four-rung jump to 0.52, and the game held 145 fps at 832x468 for the next
|
|
80
|
+
* forty seconds — a third of its pixels surrendered to fix a frame rate that was never missed.
|
|
81
|
+
* The window's own record carried the contradiction the whole time and nothing read it.
|
|
82
|
+
*
|
|
83
|
+
* A down-step is also the wrong medicine specifically here: the resize reallocates every render
|
|
84
|
+
* target, which rebuilds pipelines, which is what stalled in the first place.
|
|
85
|
+
*
|
|
86
|
+
* Ten is chosen to separate the two regimes rather than to tune a result, and the numbers are
|
|
87
|
+
* not close. A vsync-capped panel dropping frames — the case `fps`-from-mean exists to catch —
|
|
88
|
+
* has a p99 of one extra panel period, so a ratio near 2; a game that is simply slow has a ratio
|
|
89
|
+
* near 1. The lumen-hall window's ratio was 200. Nothing real sits between.
|
|
90
|
+
*/
|
|
91
|
+
stallP99Multiple: 10,
|
|
92
|
+
/**
|
|
93
|
+
* p99 needs at least three bad samples in a 300-frame window. One profiler or debugger pause can
|
|
94
|
+
* still pull fps-from-mean below the down threshold, so the maximum gets the same stall test.
|
|
95
|
+
* Ordinary missed presents are around 2x p50 and stay far below this boundary.
|
|
96
|
+
*/
|
|
97
|
+
stallMaxMultiple: 10,
|
|
98
|
+
/** React to a deficit immediately; climb only on sustained evidence. Asymmetric by design. */
|
|
99
|
+
downWindows: 1,
|
|
100
|
+
upWindows: 4,
|
|
101
|
+
/** Eight frames for the sampled GPU reading plus eight for asynchronous query resolution. */
|
|
102
|
+
maxGpuAgeFrames: 16,
|
|
103
|
+
/** Window GPU samples that make the window's own median fresh evidence; see `IScalerWindow.gpu`. */
|
|
104
|
+
minWindowGpuSamples: 4,
|
|
105
|
+
/** The resize frame is itself a hitch and must never feed the controller. */
|
|
106
|
+
cooldownWindows: 1,
|
|
107
|
+
/** Continuous sub-rectangle changes are separated by this many rendered frames. */
|
|
108
|
+
continuousChangeFrames: 8,
|
|
109
|
+
/** Ignore a continuous estimate that moves less than this fraction of the current scale. */
|
|
110
|
+
continuousChangeThreshold: 0.02,
|
|
111
|
+
/** Move this fraction of the way toward an up-estimate to preserve temporal history. */
|
|
112
|
+
continuousUpFraction: 0.9,
|
|
113
|
+
/**
|
|
114
|
+
* Windows discarded outright at the start. "Window 1 always lies" is already the perf CLI's
|
|
115
|
+
* rule; the controller was the one consumer that believed it. A scaffolded template took its
|
|
116
|
+
* only down-step from a cold-start window reading 51.52 fps while still loading, then spent
|
|
117
|
+
* four windows climbing back to where it started.
|
|
118
|
+
*/
|
|
119
|
+
warmupWindows: 1,
|
|
120
|
+
/**
|
|
121
|
+
* The most rungs one down-step may cross. Applies only when fresh GPU timing sizes the
|
|
122
|
+
* jump; without it the fallback below probes a single rung and refunds what earns nothing.
|
|
123
|
+
*
|
|
124
|
+
* Falling one rung per decision costs about twenty seconds per rung at the top of the ladder,
|
|
125
|
+
* and the ladder is ten rungs deep — a game starting at DPR-1 physical spent about three
|
|
126
|
+
* minutes visibly at 29 fps before settling. The jump size comes from the deficit: one window
|
|
127
|
+
* cannot separate the fixed cost from the pixel cost, so it attributes the whole deficit to
|
|
128
|
+
* pixels when GPU timing is unavailable. With fresh GPU timing, the GPU deficit sizes the
|
|
129
|
+
* jump instead: host delay cannot be recovered by surrendering pixels.
|
|
130
|
+
*/
|
|
131
|
+
maxDownRungs: 4,
|
|
132
|
+
/**
|
|
133
|
+
* Two down-up-down cycles across one boundary inhibit upward probes for this many windows.
|
|
134
|
+
*
|
|
135
|
+
* The PRD pre-registered this reach as 3 windows. That value cannot fire: a down-then-up leg
|
|
136
|
+
* costs at least `cooldownWindows + upWindows` = 5 windows by the rest of this same table, so a
|
|
137
|
+
* 3-window reach only ever sees the up-then-down leg and the guard is dead code. The reach is
|
|
138
|
+
* therefore derived from the table rather than picked — the tightest a down-up leg can be, plus
|
|
139
|
+
* one — and the correction is recorded in the PRD instead of being tuned in here.
|
|
140
|
+
*/
|
|
141
|
+
oscillationCycles: 2,
|
|
142
|
+
oscillationWindows: 1 + 4 + 1,
|
|
143
|
+
/**
|
|
144
|
+
* The insensitivity guard. A downward step is a hypothesis — fewer pixels will buy a faster
|
|
145
|
+
* frame — and it is only paid when the measured GPU cost falls with the pixels. On a scene whose
|
|
146
|
+
* cost is geometry, shadow maps or host work, `gpuMs` stays flat and the controller walks the
|
|
147
|
+
* picture to the floor with the frame exactly as slow: a real browser arm held `GPU p50` of
|
|
148
|
+
* 4-11 ms at scale 0.23 against 6-20 ms at scale 1.
|
|
149
|
+
*
|
|
150
|
+
* After a downward step the scaler compares the GPU time that motivated the step against the GPU
|
|
151
|
+
* time at the new rung. A relative gain below `insensitiveGainFraction`, on a step that cut at
|
|
152
|
+
* least `insensitiveMinPixelDrop` of the pixels, means the cost is not pixel-bound: the step is
|
|
153
|
+
* refunded, the rung it came from becomes the floor, and no further pixels are spent until
|
|
154
|
+
* `insensitiveRiseFraction` of sustained rise shows the workload changed.
|
|
155
|
+
*/
|
|
156
|
+
insensitiveGainFraction: 0.1,
|
|
157
|
+
insensitiveMinPixelDrop: 0.2,
|
|
158
|
+
/** A rise of the measured signal over this multiple is a changed workload, not the same one. */
|
|
159
|
+
insensitiveRiseFraction: 1.25,
|
|
160
|
+
/** Consecutive above-`insensitiveRiseFraction` windows needed to clear the memory. */
|
|
161
|
+
insensitiveResetWindows: 2,
|
|
162
|
+
/** A restored rung is held this many windows before any downward probe is reconsidered. */
|
|
163
|
+
insensitiveHoldWindows: 2,
|
|
164
|
+
/**
|
|
165
|
+
* Marker gap: one line per this many windows, so at most one per 5 s at a 120 fps target on the
|
|
166
|
+
* 300-frame report window and longer below it, never shorter.
|
|
167
|
+
*/
|
|
168
|
+
insensitiveMarkerWindows: 2,
|
|
169
|
+
} as const;
|
|
170
|
+
|
|
171
|
+
/** Printed when a downward step is refunded because the frame did not respond to the pixels. */
|
|
172
|
+
export const RESOLUTION_SCALE_INSENSITIVE_MARKER = "TN_RESOLUTION_SCALE_INSENSITIVE";
|
|
173
|
+
|
|
174
|
+
/** Pixels retained per rung: 0.85 linear on each axis. */
|
|
175
|
+
const RUNG_PIXEL_RATIO = 0.85 * 0.85;
|
|
176
|
+
|
|
177
|
+
/** One rung value to its index, failing closed on anything the ladder does not contain. */
|
|
178
|
+
function rungIndex(value: number, label: string): number {
|
|
179
|
+
const index = RESOLUTION_SCALER.rungs.indexOf(value as never);
|
|
180
|
+
if (index < 0)
|
|
181
|
+
throw new Error(
|
|
182
|
+
`ResolutionScaler ${label} must be one of the pre-registered rung values, received ${String(value)}.`,
|
|
183
|
+
);
|
|
184
|
+
return index;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
export interface IResolutionScalerOptions {
|
|
188
|
+
/** The `display.maxFps` the loop is holding the budget against. */
|
|
189
|
+
readonly targetFps: number;
|
|
190
|
+
/** Which rung to start on. Must be one of the rungs; defaults to the ceiling. */
|
|
191
|
+
readonly start?: number;
|
|
192
|
+
/**
|
|
193
|
+
* The lowest rung this platform may take, and the rung `atFloor` is reported at. Must be one of
|
|
194
|
+
* the rungs; defaults to the last one, which is the whole ladder the device arm measured with.
|
|
195
|
+
* A desktop host passes `RESOLUTION_SCALER.desktopFloorScale`.
|
|
196
|
+
*/
|
|
197
|
+
readonly minScale?: number;
|
|
198
|
+
/**
|
|
199
|
+
* Read whenever the floor is consulted, so the scaler can see a render chain that arrived or
|
|
200
|
+
* changed under it: a chain that reconstructs a display-resolution frame from these pixels
|
|
201
|
+
* lifts the floor for as long as it is installed.
|
|
202
|
+
*/
|
|
203
|
+
readonly temporalUpscale?: () => boolean;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/** A closed frame-budget window's presentation distribution and optional GPU observation. */
|
|
207
|
+
export interface IScalerWindow {
|
|
208
|
+
/** The last resolved GPU duration and its age; absent/old observations may only probe. */
|
|
209
|
+
readonly gpuMs?: number;
|
|
210
|
+
readonly gpuAgeFrames?: number;
|
|
211
|
+
/**
|
|
212
|
+
* This window's own GPU samples. When the last resolve is past `maxGpuAgeFrames` but the window
|
|
213
|
+
* holds `minWindowGpuSamples` of them, their median stands in: they were drawn in this window.
|
|
214
|
+
*/
|
|
215
|
+
readonly gpu?: { readonly p50: number; readonly samples: number };
|
|
216
|
+
/** Frames per second this window achieved, from the mean presented interval. */
|
|
217
|
+
readonly fps: number;
|
|
218
|
+
/** Loop frames represented by this closed window, used for the sub-rectangle cadence guard. */
|
|
219
|
+
readonly frames?: number;
|
|
220
|
+
/** Current drawing surface, used to quantize a continuous estimate to eight pixels. */
|
|
221
|
+
readonly surface?: {
|
|
222
|
+
readonly drawingBufferWidth: number;
|
|
223
|
+
readonly drawingBufferHeight: number;
|
|
224
|
+
readonly resolutionScale: number;
|
|
225
|
+
readonly resolutionSubrect?: boolean;
|
|
226
|
+
};
|
|
227
|
+
/**
|
|
228
|
+
* `p50` says what an ordinary frame cost; `p99` and `max` expose recurring and isolated stalls.
|
|
229
|
+
* The controller needs them to tell a slow game from a stalled one: `fps` alone cannot, because
|
|
230
|
+
* it comes from a mean.
|
|
231
|
+
*/
|
|
232
|
+
readonly presented: {
|
|
233
|
+
readonly max: number;
|
|
234
|
+
readonly p50: number;
|
|
235
|
+
readonly p95: number;
|
|
236
|
+
readonly p99: number;
|
|
237
|
+
};
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
export class ResolutionScaler {
|
|
241
|
+
/** fps at or above this is meeting the target. Mutable only through `retarget`. */
|
|
242
|
+
// The three budget fields are placeholders the constructor overwrites before anything can read
|
|
243
|
+
// them; TypeScript cannot see that through the `retarget` call every constructor makes.
|
|
244
|
+
targetFps = 0;
|
|
245
|
+
/**
|
|
246
|
+
* A presented interval above this is a frame that cost more than the target allows: the same
|
|
247
|
+
* bar `targetFps` is, read as a period instead of a rate. Nothing new is chosen here — it is
|
|
248
|
+
* `targetFpsFraction` again, applied to the statistic a mean cannot speak for.
|
|
249
|
+
*/
|
|
250
|
+
budgetMs = 0;
|
|
251
|
+
/** presented p95 above this is dropping frames, whatever the mean says. */
|
|
252
|
+
tailMs = 0;
|
|
253
|
+
#index: number;
|
|
254
|
+
#continuousScale: number;
|
|
255
|
+
/** The lowest rung this platform may take; the whole ladder's last index when it states none. */
|
|
256
|
+
readonly #minIndex: number;
|
|
257
|
+
readonly #temporalUpscale: (() => boolean) | undefined;
|
|
258
|
+
#scaleSource: Exclude<ScaleSource, "pinned"> = "auto";
|
|
259
|
+
#cleanWindows = 0;
|
|
260
|
+
#cooldown = 0;
|
|
261
|
+
#warmup = RESOLUTION_SCALER.warmupWindows;
|
|
262
|
+
#windowIndex = 0;
|
|
263
|
+
// Oscillation state. A "boundary" is the higher of the two rungs a step crossed, so a fall
|
|
264
|
+
// from 1.0 and the climb back to it are recognised as the same boundary.
|
|
265
|
+
#guardBoundary = -1;
|
|
266
|
+
#guardDirection = 0;
|
|
267
|
+
#guardLegs = 0;
|
|
268
|
+
#guardCycles = 0;
|
|
269
|
+
#guardWindow = 0;
|
|
270
|
+
#pinWindows = 0;
|
|
271
|
+
// Unknown-GPU probe state. A down-step taken without fresh GPU timing is a hypothesis —
|
|
272
|
+
// fewer pixels will recover the frame rate — and the next decided window tests it against
|
|
273
|
+
// the fps that motivated it. `#probeBlind` records a failed hypothesis: reprobing the same
|
|
274
|
+
// host-bound workload would only flicker, so unknown-GPU probes stop until fresh timing or
|
|
275
|
+
// a recovered frame rate reopens the question. `#lastHealthyWindow` records the last window
|
|
276
|
+
// whose fresh GPU timing showed headroom, so a single gap after healthy timing holds
|
|
277
|
+
// instead of probing.
|
|
278
|
+
#probeFps: number | undefined = undefined;
|
|
279
|
+
#probeBlind = false;
|
|
280
|
+
#lastHealthyWindow = 0;
|
|
281
|
+
// Insensitivity memory. `#insensitiveProbe` is the outstanding hypothesis of a fresh-GPU
|
|
282
|
+
// downward step; `#insensitiveFloor` is the rung a refunded one proved worth holding (no
|
|
283
|
+
// downward step may cross it while it stands), `#insensitiveSignal` its measured GPU time, and
|
|
284
|
+
// `#insensitiveRise` the consecutive windows of sustained rise that clear both.
|
|
285
|
+
#insensitiveProbe:
|
|
286
|
+
| { fromIndex: number; toIndex: number; fromScale?: number; toScale?: number; signal: number }
|
|
287
|
+
| undefined = undefined;
|
|
288
|
+
#insensitiveFloor = -1;
|
|
289
|
+
#insensitiveSignal = 0;
|
|
290
|
+
#insensitiveRise = 0;
|
|
291
|
+
#insensitiveHold = 0;
|
|
292
|
+
#lastInsensitiveMarker = Number.NEGATIVE_INFINITY;
|
|
293
|
+
#continuousFrames = 0;
|
|
294
|
+
#continuousLastChangeFrame = Number.NEGATIVE_INFINITY;
|
|
295
|
+
|
|
296
|
+
constructor(options: IResolutionScalerOptions) {
|
|
297
|
+
const { minScale, start, targetFps, temporalUpscale } = options;
|
|
298
|
+
this.retarget(targetFps);
|
|
299
|
+
this.#index = start === undefined ? 0 : rungIndex(start, "start");
|
|
300
|
+
this.#continuousScale = RESOLUTION_SCALER.rungs[this.#index] ?? 1;
|
|
301
|
+
this.#minIndex =
|
|
302
|
+
minScale === undefined ? RESOLUTION_SCALER.rungs.length - 1 : rungIndex(minScale, "minScale");
|
|
303
|
+
this.#temporalUpscale = temporalUpscale;
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
/**
|
|
307
|
+
* Re-reads the budget when the engine's resolved display target changes.
|
|
308
|
+
*
|
|
309
|
+
* The web cannot know a panel's rate before it has presented a window's worth of frames, so a
|
|
310
|
+
* 120 Hz display starts on the 60 fallback and moves. The rungs and every decision already made
|
|
311
|
+
* stay: only the bar the next window is judged against changes, and a target that is not a
|
|
312
|
+
* positive rate throws exactly as it does in the constructor.
|
|
313
|
+
*/
|
|
314
|
+
retarget(targetFps: number): void {
|
|
315
|
+
if (!Number.isFinite(targetFps) || targetFps <= 0)
|
|
316
|
+
throw new Error(
|
|
317
|
+
`ResolutionScaler targetFps must be a finite number greater than zero, received ${String(targetFps)}.`,
|
|
318
|
+
);
|
|
319
|
+
this.targetFps = targetFps * RESOLUTION_SCALER.targetFpsFraction;
|
|
320
|
+
this.budgetMs = 1000 / this.targetFps;
|
|
321
|
+
this.tailMs = (1000 / targetFps) * RESOLUTION_SCALER.upTailFraction;
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
/** The scale the renderer should be applying right now. */
|
|
325
|
+
get scale(): number {
|
|
326
|
+
return this.#continuousScale;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/**
|
|
330
|
+
* The lowest rung the scaler may take right now. The platform's own floor, lifted for as long
|
|
331
|
+
* as the render chain reconstructs the frame from the pixels it is being asked to surrender.
|
|
332
|
+
*/
|
|
333
|
+
get #limitIndex(): number {
|
|
334
|
+
return this.#temporalUpscale?.() === true ? RESOLUTION_SCALER.rungs.length - 1 : this.#minIndex;
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
get scaleSource(): Exclude<ScaleSource, "pinned"> {
|
|
338
|
+
return this.#scaleSource;
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
/**
|
|
342
|
+
* True when the floor is reached and the tail is still over budget. The window keeps reporting
|
|
343
|
+
* the true scale: a scaler that ran out of room must say so rather than let the number read as
|
|
344
|
+
* a met budget.
|
|
345
|
+
*/
|
|
346
|
+
get atFloor(): boolean {
|
|
347
|
+
return this.#atFloor;
|
|
348
|
+
}
|
|
349
|
+
#atFloor = false;
|
|
350
|
+
|
|
351
|
+
/**
|
|
352
|
+
* Feeds one completed frame-budget window. Returns the new scale when this window caused a
|
|
353
|
+
* step, `undefined` otherwise. Allocation-free: no object is constructed on the steady path.
|
|
354
|
+
*/
|
|
355
|
+
observe(window: IScalerWindow): number | undefined {
|
|
356
|
+
this.#windowIndex += 1;
|
|
357
|
+
const frames = window.frames;
|
|
358
|
+
this.#continuousFrames +=
|
|
359
|
+
frames !== undefined && Number.isFinite(frames) && frames > 0 ? Math.floor(frames) : 1;
|
|
360
|
+
if (this.#scaleSource === "auto-pinned" && --this.#pinWindows === 0) {
|
|
361
|
+
this.#scaleSource = "auto";
|
|
362
|
+
this.#guardLegs = this.#guardCycles = this.#cleanWindows = 0;
|
|
363
|
+
// The loop propagates scaleSource only when a scale is returned, including an unchanged one.
|
|
364
|
+
return this.scale;
|
|
365
|
+
}
|
|
366
|
+
if (this.#warmup > 0) {
|
|
367
|
+
this.#warmup -= 1;
|
|
368
|
+
return undefined;
|
|
369
|
+
}
|
|
370
|
+
if (this.#cooldown > 0) {
|
|
371
|
+
this.#cooldown -= 1;
|
|
372
|
+
return undefined;
|
|
373
|
+
}
|
|
374
|
+
// A stalled window is not a measurement of the frame rate, in either direction: acting on the
|
|
375
|
+
// mean would cut resolution the game did not need, and counting it clean would climb on a
|
|
376
|
+
// window that was mostly spent stopped. Deferring means neither — the clean run it interrupts
|
|
377
|
+
// is left standing rather than thrown away. Resetting it made the up-path unreachable for any
|
|
378
|
+
// game that hitches more often than once every `cooldownWindows + upWindows` windows: one
|
|
379
|
+
// 400 ms frame every third window pinned a scaler at 0.44 through seventeen minutes of
|
|
380
|
+
// otherwise perfect 60 fps, which is a forest streaming its next hillside.
|
|
381
|
+
//
|
|
382
|
+
// Unless the stalls are not what makes the frame slow: a weak GPU whose shadow redraws stall
|
|
383
|
+
// every window and whose ordinary frame still misses the budget is judged on that frame,
|
|
384
|
+
// downward only (see `#slowUnderStalls`).
|
|
385
|
+
const stalled = this.#stalled(window);
|
|
386
|
+
if (stalled && !this.#slowUnderStalls(window)) return undefined;
|
|
387
|
+
const gpuMs = this.#freshGpuMs(window);
|
|
388
|
+
this.#noteGpuObservation(window, gpuMs);
|
|
389
|
+
if (this.#insensitiveHold > 0) this.#insensitiveHold -= 1;
|
|
390
|
+
this.#trackInsensitiveRise(gpuMs);
|
|
391
|
+
const refunded = this.#settleInsensitiveProbe(gpuMs);
|
|
392
|
+
if (refunded !== undefined) return refunded;
|
|
393
|
+
if (gpuMs !== undefined && this.#continuousActive(window))
|
|
394
|
+
return this.#observeContinuous(window, gpuMs, stalled);
|
|
395
|
+
if (window.fps < this.targetFps && (gpuMs === undefined || gpuMs > this.budgetMs)) {
|
|
396
|
+
// **Only the mean is under target: hold.** `fps` is `1000 / mean`, and on the one panel
|
|
397
|
+
// arrangement every game actually ships into — `display.maxFps` equal to the refresh rate,
|
|
398
|
+
// vsync on — the mean is the only statistic with any room to move. fps is bounded *above*
|
|
399
|
+
// by the target there, so the whole test lives in the 2% under it, and each present the
|
|
400
|
+
// compositor drops spends a third of a percent. Seven doubled intervals out of 300 crossed
|
|
401
|
+
// the bar on `sandbox/wildwood` while the median and the tail both sat on the panel period,
|
|
402
|
+
// and fewer pixels do not bring a dropped present back: the step won nothing, the next
|
|
403
|
+
// window spent another rung, and the picture walked to 5% of its pixels in 140 seconds.
|
|
404
|
+
// This is `stallP99Multiple`'s lesson at 2x rather than at 10x.
|
|
405
|
+
//
|
|
406
|
+
// Deferred rather than merely not acted on, and the difference is the whole repair. Such a
|
|
407
|
+
// window says nothing about the pixel cost **in either direction**, which is exactly what
|
|
408
|
+
// the stall guard above says about its own case — so it is neither grounds to fall nor a
|
|
409
|
+
// reason to throw away the clean run a climb needs. Counting it against the climb stops the
|
|
410
|
+
// descent and never gives the pixels back: replayed against the state `sandbox/wildwood`'s
|
|
411
|
+
// own record documents — parked at 0.61 while holding 60.0 fps — that reading held 0.61 for
|
|
412
|
+
// five minutes. The picture stops getting worse and never gets sharp again, which is half a
|
|
413
|
+
// fix and the wrong half.
|
|
414
|
+
if (!this.#overBudget(window)) return undefined;
|
|
415
|
+
this.#cleanWindows = 0;
|
|
416
|
+
// Unknown GPU timing is not evidence of a GPU bottleneck: an adapter without timestamp
|
|
417
|
+
// queries reports nothing either way, and neither this window's fps nor its presentation
|
|
418
|
+
// tail can separate fixed host cost from pixel cost. So the fallback may only probe —
|
|
419
|
+
// one rung down, refunded unless fewer pixels earn a better frame rate.
|
|
420
|
+
// The memory holds both kinds of probe: a workload already shown not to answer to pixels
|
|
421
|
+
// does not become pixel-bound just because this window lost its GPU timestamp.
|
|
422
|
+
if (this.#insensitiveHold > 0 || this.#insensitiveFloor >= 0) return undefined;
|
|
423
|
+
if (gpuMs === undefined) return this.#probeUnknown(window);
|
|
424
|
+
if (this.#index >= this.#limitIndex) {
|
|
425
|
+
this.#atFloor = true;
|
|
426
|
+
return undefined;
|
|
427
|
+
}
|
|
428
|
+
const fromIndex = this.#index;
|
|
429
|
+
const stepped = this.#step(this.#rungsToDrop(1000 / gpuMs));
|
|
430
|
+
// Record the hypothesis only for a fresh-GPU step: that is the signal that can separate
|
|
431
|
+
// pixel cost from host cost, and a step the oscillation guard has just pinned is not one
|
|
432
|
+
// the next window will be allowed to test.
|
|
433
|
+
if (this.#scaleSource === "auto") {
|
|
434
|
+
const pixelDrop = 1 - (this.scale / (RESOLUTION_SCALER.rungs[fromIndex] ?? 1)) ** 2;
|
|
435
|
+
if (pixelDrop >= RESOLUTION_SCALER.insensitiveMinPixelDrop)
|
|
436
|
+
this.#insensitiveProbe = { fromIndex, toIndex: this.#index, signal: gpuMs };
|
|
437
|
+
}
|
|
438
|
+
return stepped;
|
|
439
|
+
}
|
|
440
|
+
this.#atFloor = false;
|
|
441
|
+
// A stalled window is never grounds to climb.
|
|
442
|
+
if (stalled) return undefined;
|
|
443
|
+
if (this.#scaleSource === "auto-pinned") return undefined;
|
|
444
|
+
const nextScale = RESOLUTION_SCALER.rungs[Math.max(0, this.#index - 1)] ?? 1;
|
|
445
|
+
const canClimb =
|
|
446
|
+
gpuMs === undefined
|
|
447
|
+
? window.presented.p95 <= this.tailMs
|
|
448
|
+
: gpuMs * (nextScale / this.scale) ** 2 <= this.budgetMs;
|
|
449
|
+
if (!canClimb) {
|
|
450
|
+
this.#cleanWindows = 0;
|
|
451
|
+
return undefined;
|
|
452
|
+
}
|
|
453
|
+
this.#cleanWindows += 1;
|
|
454
|
+
if (this.#cleanWindows < RESOLUTION_SCALER.upWindows) return undefined;
|
|
455
|
+
this.#cleanWindows = 0;
|
|
456
|
+
if (this.#index === 0) return undefined;
|
|
457
|
+
return this.#step(-1);
|
|
458
|
+
}
|
|
459
|
+
|
|
460
|
+
/**
|
|
461
|
+
* Records what this window's GPU observation settles about earlier inferences. Fresh timing
|
|
462
|
+
* supersedes everything drawn from its absence; a recovered frame rate reopens a question a
|
|
463
|
+
* failed probe closed, because the workload changed.
|
|
464
|
+
*/
|
|
465
|
+
#noteGpuObservation(window: IScalerWindow, gpuMs: number | undefined): void {
|
|
466
|
+
if (gpuMs !== undefined) {
|
|
467
|
+
this.#probeFps = undefined;
|
|
468
|
+
this.#probeBlind = false;
|
|
469
|
+
if (gpuMs <= this.budgetMs) this.#lastHealthyWindow = this.#windowIndex;
|
|
470
|
+
} else if (window.fps >= this.targetFps) {
|
|
471
|
+
this.#probeFps = undefined;
|
|
472
|
+
this.#probeBlind = false;
|
|
473
|
+
}
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
/**
|
|
477
|
+
* Settles the outstanding insensitivity hypothesis against this window's fresh GPU time. Returns
|
|
478
|
+
* the restored scale when the step is refunded, `undefined` when it earned its pixels or there is
|
|
479
|
+
* nothing to settle. A window without fresh timing waits rather than guessing.
|
|
480
|
+
*/
|
|
481
|
+
#settleInsensitiveProbe(gpuMs: number | undefined): number | undefined {
|
|
482
|
+
const probe = this.#insensitiveProbe;
|
|
483
|
+
if (probe === undefined || gpuMs === undefined) return undefined;
|
|
484
|
+
this.#insensitiveProbe = undefined;
|
|
485
|
+
const gain = (probe.signal - gpuMs) / probe.signal;
|
|
486
|
+
if (gain >= RESOLUTION_SCALER.insensitiveGainFraction) return undefined;
|
|
487
|
+
const restored = probe.fromScale ?? RESOLUTION_SCALER.rungs[probe.fromIndex] ?? 1;
|
|
488
|
+
this.#index = probe.fromIndex;
|
|
489
|
+
this.#continuousScale = restored;
|
|
490
|
+
this.#insensitiveFloor = probe.fromIndex;
|
|
491
|
+
this.#insensitiveSignal = probe.signal;
|
|
492
|
+
this.#insensitiveHold = RESOLUTION_SCALER.insensitiveHoldWindows;
|
|
493
|
+
this.#cleanWindows = 0;
|
|
494
|
+
// The restore is itself a resize and must not feed the controller.
|
|
495
|
+
this.#cooldown = RESOLUTION_SCALER.cooldownWindows;
|
|
496
|
+
this.#emitInsensitive(
|
|
497
|
+
probe.toScale ?? RESOLUTION_SCALER.rungs[probe.toIndex] ?? 1,
|
|
498
|
+
restored,
|
|
499
|
+
gain,
|
|
500
|
+
);
|
|
501
|
+
return restored;
|
|
502
|
+
}
|
|
503
|
+
|
|
504
|
+
/**
|
|
505
|
+
* Clears the memory once the measured signal has risen past `insensitiveRiseFraction` for
|
|
506
|
+
* `insensitiveResetWindows` windows: a heavier workload may be pixel-bound where the old one was
|
|
507
|
+
* not, and the floor it set must not lock the picture soft for the rest of the session.
|
|
508
|
+
*/
|
|
509
|
+
#trackInsensitiveRise(gpuMs: number | undefined): void {
|
|
510
|
+
if (this.#insensitiveFloor < 0 || gpuMs === undefined) return;
|
|
511
|
+
if (gpuMs <= this.#insensitiveSignal * RESOLUTION_SCALER.insensitiveRiseFraction) {
|
|
512
|
+
this.#insensitiveRise = 0;
|
|
513
|
+
return;
|
|
514
|
+
}
|
|
515
|
+
this.#insensitiveRise += 1;
|
|
516
|
+
if (this.#insensitiveRise < RESOLUTION_SCALER.insensitiveResetWindows) return;
|
|
517
|
+
this.#insensitiveFloor = -1;
|
|
518
|
+
this.#insensitiveSignal = 0;
|
|
519
|
+
this.#insensitiveRise = 0;
|
|
520
|
+
this.#insensitiveHold = 0;
|
|
521
|
+
}
|
|
522
|
+
|
|
523
|
+
/** One marker per refunded step, no more often than `insensitiveMarkerWindows`. */
|
|
524
|
+
#emitInsensitive(scale: number, restored: number, gain: number): void {
|
|
525
|
+
if (
|
|
526
|
+
this.#windowIndex - this.#lastInsensitiveMarker <
|
|
527
|
+
RESOLUTION_SCALER.insensitiveMarkerWindows
|
|
528
|
+
)
|
|
529
|
+
return;
|
|
530
|
+
this.#lastInsensitiveMarker = this.#windowIndex;
|
|
531
|
+
console.info(
|
|
532
|
+
`${RESOLUTION_SCALE_INSENSITIVE_MARKER} scale=${String(scale)} restored=${String(restored)} gainPct=${String(Math.round(gain * 100))}`,
|
|
533
|
+
);
|
|
534
|
+
}
|
|
535
|
+
|
|
536
|
+
/**
|
|
537
|
+
* One decided over-budget window with no fresh GPU timing. Returns the new scale when this
|
|
538
|
+
* window caused a step, `undefined` otherwise.
|
|
539
|
+
*/
|
|
540
|
+
#probeUnknown(window: IScalerWindow): number | undefined {
|
|
541
|
+
// A pending probe is evaluated before the floor guard: parking at the final rung must
|
|
542
|
+
// not strand the hypothesis that fewer pixels would help. Improvement counts only when
|
|
543
|
+
// the new deficit prices fewer rungs than the old one — the same rung table as every
|
|
544
|
+
// sized jump, so timing noise that never crosses a rung boundary refunds instead of
|
|
545
|
+
// ratcheting the ladder down one tremor at a time.
|
|
546
|
+
if (this.#probeFps !== undefined) {
|
|
547
|
+
const earned = this.#rungsToDrop(window.fps) < this.#rungsToDrop(this.#probeFps);
|
|
548
|
+
this.#probeFps = undefined;
|
|
549
|
+
if (!earned) {
|
|
550
|
+
this.#probeBlind = true;
|
|
551
|
+
return this.#step(-1, false);
|
|
552
|
+
}
|
|
553
|
+
if (this.#index >= this.#limitIndex) {
|
|
554
|
+
this.#atFloor = true;
|
|
555
|
+
return undefined;
|
|
556
|
+
}
|
|
557
|
+
this.#probeFps = window.fps;
|
|
558
|
+
return this.#step(1);
|
|
559
|
+
}
|
|
560
|
+
if (this.#index >= this.#limitIndex) {
|
|
561
|
+
this.#atFloor = true;
|
|
562
|
+
return undefined;
|
|
563
|
+
}
|
|
564
|
+
// A gap immediately after fresh-healthy timing is transient, not a new bottleneck.
|
|
565
|
+
if (this.#windowIndex - this.#lastHealthyWindow <= 1) return undefined;
|
|
566
|
+
if (this.#probeBlind) return undefined;
|
|
567
|
+
this.#probeFps = window.fps;
|
|
568
|
+
return this.#step(1);
|
|
569
|
+
}
|
|
570
|
+
|
|
571
|
+
#continuousActive(window: IScalerWindow): boolean {
|
|
572
|
+
return window.surface?.resolutionSubrect === true;
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
#observeContinuous(
|
|
576
|
+
window: IScalerWindow,
|
|
577
|
+
gpuMs: number | undefined,
|
|
578
|
+
stalled: boolean,
|
|
579
|
+
): number | undefined {
|
|
580
|
+
const overBudget =
|
|
581
|
+
window.fps < this.targetFps && (gpuMs === undefined || gpuMs > this.budgetMs);
|
|
582
|
+
const floor = RESOLUTION_SCALER.rungs[this.#limitIndex] ?? 0.23;
|
|
583
|
+
if (overBudget) {
|
|
584
|
+
this.#cleanWindows = 0;
|
|
585
|
+
if (!this.#overBudget(window) || gpuMs === undefined) {
|
|
586
|
+
this.#atFloor = this.#continuousScale <= floor;
|
|
587
|
+
return undefined;
|
|
588
|
+
}
|
|
589
|
+
if (this.#insensitiveHold > 0 || this.#insensitiveFloor >= 0) return undefined;
|
|
590
|
+
const estimate = this.#continuousScale * Math.sqrt(this.budgetMs / gpuMs);
|
|
591
|
+
const target = this.#quantizeContinuous(Math.max(floor, estimate), window);
|
|
592
|
+
this.#atFloor = target <= floor;
|
|
593
|
+
const fromIndex = this.#index;
|
|
594
|
+
const fromScale = this.#continuousScale;
|
|
595
|
+
const changed = this.#continuousChange(Math.max(floor, target), false);
|
|
596
|
+
if (
|
|
597
|
+
changed !== undefined &&
|
|
598
|
+
this.#scaleSource === "auto" &&
|
|
599
|
+
1 - (changed / fromScale) ** 2 >= RESOLUTION_SCALER.insensitiveMinPixelDrop
|
|
600
|
+
)
|
|
601
|
+
this.#insensitiveProbe = {
|
|
602
|
+
fromIndex,
|
|
603
|
+
toIndex: this.#index,
|
|
604
|
+
fromScale,
|
|
605
|
+
toScale: changed,
|
|
606
|
+
signal: gpuMs,
|
|
607
|
+
};
|
|
608
|
+
return changed;
|
|
609
|
+
}
|
|
610
|
+
this.#atFloor = false;
|
|
611
|
+
if (stalled || this.#scaleSource === "auto-pinned") return undefined;
|
|
612
|
+
const nextScale = Math.min(1, this.#continuousScale + 0.01);
|
|
613
|
+
const canClimb =
|
|
614
|
+
gpuMs === undefined
|
|
615
|
+
? window.presented.p95 <= this.tailMs
|
|
616
|
+
: gpuMs * (nextScale / this.#continuousScale) ** 2 <= this.budgetMs;
|
|
617
|
+
if (!canClimb) {
|
|
618
|
+
this.#cleanWindows = 0;
|
|
619
|
+
return undefined;
|
|
620
|
+
}
|
|
621
|
+
this.#cleanWindows += 1;
|
|
622
|
+
if (this.#cleanWindows < RESOLUTION_SCALER.upWindows) return undefined;
|
|
623
|
+
this.#cleanWindows = 0;
|
|
624
|
+
const estimate =
|
|
625
|
+
gpuMs === undefined
|
|
626
|
+
? 1
|
|
627
|
+
: Math.min(1, this.#continuousScale * Math.sqrt(this.budgetMs / gpuMs));
|
|
628
|
+
const amortized =
|
|
629
|
+
this.#continuousScale +
|
|
630
|
+
RESOLUTION_SCALER.continuousUpFraction *
|
|
631
|
+
(Math.max(this.#continuousScale, estimate) - this.#continuousScale);
|
|
632
|
+
return this.#continuousChange(this.#quantizeContinuous(amortized, window), true);
|
|
633
|
+
}
|
|
634
|
+
|
|
635
|
+
#quantizeContinuous(scale: number, window: IScalerWindow): number {
|
|
636
|
+
const surface = window.surface;
|
|
637
|
+
if (
|
|
638
|
+
surface === undefined ||
|
|
639
|
+
!Number.isFinite(surface.drawingBufferWidth) ||
|
|
640
|
+
!Number.isFinite(surface.drawingBufferHeight) ||
|
|
641
|
+
!Number.isFinite(surface.resolutionScale) ||
|
|
642
|
+
surface.drawingBufferWidth <= 0 ||
|
|
643
|
+
surface.drawingBufferHeight <= 0 ||
|
|
644
|
+
surface.resolutionScale <= 0
|
|
645
|
+
)
|
|
646
|
+
return Math.min(1, Math.max(0, scale));
|
|
647
|
+
const fullWidth =
|
|
648
|
+
surface.resolutionSubrect === true
|
|
649
|
+
? surface.drawingBufferWidth
|
|
650
|
+
: surface.drawingBufferWidth / surface.resolutionScale;
|
|
651
|
+
const fullHeight =
|
|
652
|
+
surface.resolutionSubrect === true
|
|
653
|
+
? surface.drawingBufferHeight
|
|
654
|
+
: surface.drawingBufferHeight / surface.resolutionScale;
|
|
655
|
+
const width = Math.max(8, Math.ceil((fullWidth * scale) / 8) * 8);
|
|
656
|
+
const height = Math.max(8, Math.ceil((fullHeight * scale) / 8) * 8);
|
|
657
|
+
return Math.min(1, width / fullWidth, height / fullHeight);
|
|
658
|
+
}
|
|
659
|
+
|
|
660
|
+
#continuousChange(target: number, up: boolean): number | undefined {
|
|
661
|
+
const current = this.#continuousScale;
|
|
662
|
+
const change = Math.abs(target - current) / Math.max(current, Number.EPSILON);
|
|
663
|
+
if (change < RESOLUTION_SCALER.continuousChangeThreshold) return undefined;
|
|
664
|
+
if (
|
|
665
|
+
this.#continuousFrames - this.#continuousLastChangeFrame <
|
|
666
|
+
RESOLUTION_SCALER.continuousChangeFrames
|
|
667
|
+
)
|
|
668
|
+
return undefined;
|
|
669
|
+
const next = Math.min(1, Math.max(RESOLUTION_SCALER.rungs[this.#limitIndex] ?? 0.23, target));
|
|
670
|
+
if (next === current) return undefined;
|
|
671
|
+
const previousIndex = this.#index;
|
|
672
|
+
this.#continuousScale = next;
|
|
673
|
+
this.#syncRungIndex(next);
|
|
674
|
+
this.#continuousLastChangeFrame = this.#continuousFrames;
|
|
675
|
+
this.#cooldown = RESOLUTION_SCALER.cooldownWindows;
|
|
676
|
+
const direction = next < current ? 1 : -1;
|
|
677
|
+
const boundary = direction > 0 ? previousIndex : this.#index;
|
|
678
|
+
this.#noteForOscillationGuard(boundary, direction);
|
|
679
|
+
return this.#continuousScale;
|
|
680
|
+
}
|
|
681
|
+
|
|
682
|
+
#syncRungIndex(scale: number): void {
|
|
683
|
+
let closest = 0;
|
|
684
|
+
let distance = Number.POSITIVE_INFINITY;
|
|
685
|
+
for (const [index, rung] of RESOLUTION_SCALER.rungs.entries()) {
|
|
686
|
+
const nextDistance = Math.abs(rung - scale);
|
|
687
|
+
if (nextDistance >= distance) continue;
|
|
688
|
+
closest = index;
|
|
689
|
+
distance = nextDistance;
|
|
690
|
+
}
|
|
691
|
+
this.#index = closest;
|
|
692
|
+
}
|
|
693
|
+
|
|
694
|
+
/**
|
|
695
|
+
* True when the median or tail corroborates the missed presentation budget. This alone cannot
|
|
696
|
+
* identify a pixel bottleneck; fresh GPU timing takes precedence in observe().
|
|
697
|
+
*
|
|
698
|
+
* Two independent witnesses, each already carrying its own pre-registered bar, and either is
|
|
699
|
+
* enough:
|
|
700
|
+
*
|
|
701
|
+
* - **the median present is over the target's period.** An unlocked renderer holding a steady
|
|
702
|
+
* 17.24 ms against a 16.67 ms budget shows up here and nowhere else: its tail is as tight as
|
|
703
|
+
* its middle, and it is simply doing too much work every frame.
|
|
704
|
+
* - **the tail is past `tailMs`.** Under FIFO an interval is a whole number of panel periods,
|
|
705
|
+
* so a game that misses a real share of its vsyncs moves p95 to two periods in one jump —
|
|
706
|
+
* the 45 fps window the device arm chose the mean signal for. There is nothing in between to
|
|
707
|
+
* fall through: `upTailFraction` sits in the empty gap between one period and two.
|
|
708
|
+
*
|
|
709
|
+
* When neither speaks, the deficit is a handful of doubled intervals in an otherwise on-budget
|
|
710
|
+
* window: jitter from the compositor, a GC, an input burst, an audio callback. None of that is
|
|
711
|
+
* bought back with pixels, and spending a rung on it is how the picture walks to the floor.
|
|
712
|
+
*/
|
|
713
|
+
/**
|
|
714
|
+
* Whether a stalled window's ordinary frame misses the budget on its own: the window is under
|
|
715
|
+
* target and fresh GPU timing alone exceeds the budget, so setting the stalls aside still leaves
|
|
716
|
+
* a slow frame that fewer pixels can speed up. A game whose GPU meets the budget keeps the stall
|
|
717
|
+
* deferral; a weak GPU does not stay at full resolution forever because its hitches recur. On an
|
|
718
|
+
* Intel Iris Xe, Machinefall's shadow redraws (120-350 ms) put presented p99 at 15-63x p50 in
|
|
719
|
+
* all but one judged window, p50 sat at 9-12 ms against 8.33, and the scale held 1.0 for the
|
|
720
|
+
* whole walk (PRD-549).
|
|
721
|
+
*/
|
|
722
|
+
#slowUnderStalls(window: IScalerWindow): boolean {
|
|
723
|
+
const gpuMs = this.#freshGpuMs(window);
|
|
724
|
+
// Fresh GPU over budget in a window under target. Not the present median: on the Iris Xe it
|
|
725
|
+
// read 7 ms while the main pass took 30 ms and the window ran at 35 fps (PRD-549, live11).
|
|
726
|
+
return window.fps < this.targetFps && gpuMs !== undefined && gpuMs > this.budgetMs;
|
|
727
|
+
}
|
|
728
|
+
|
|
729
|
+
#overBudget(window: IScalerWindow): boolean {
|
|
730
|
+
return window.presented.p50 > this.budgetMs || window.presented.p95 > this.tailMs;
|
|
731
|
+
}
|
|
732
|
+
|
|
733
|
+
#freshGpuMs({ gpu, gpuMs, gpuAgeFrames }: IScalerWindow): number | undefined {
|
|
734
|
+
if (
|
|
735
|
+
gpuMs !== undefined &&
|
|
736
|
+
Number.isFinite(gpuMs) &&
|
|
737
|
+
gpuMs > 0 &&
|
|
738
|
+
gpuAgeFrames !== undefined &&
|
|
739
|
+
Number.isInteger(gpuAgeFrames) &&
|
|
740
|
+
gpuAgeFrames >= 0 &&
|
|
741
|
+
gpuAgeFrames <= RESOLUTION_SCALER.maxGpuAgeFrames
|
|
742
|
+
)
|
|
743
|
+
return gpuMs;
|
|
744
|
+
// An integrated GPU resolves timestamps hundreds of frames late (Iris Xe: 233-593, PRD-549),
|
|
745
|
+
// so the last reading is always old while the window is full of its own samples.
|
|
746
|
+
return gpu !== undefined &&
|
|
747
|
+
gpu.samples >= RESOLUTION_SCALER.minWindowGpuSamples &&
|
|
748
|
+
Number.isFinite(gpu.p50) &&
|
|
749
|
+
gpu.p50 > 0
|
|
750
|
+
? gpu.p50
|
|
751
|
+
: undefined;
|
|
752
|
+
}
|
|
753
|
+
|
|
754
|
+
/**
|
|
755
|
+
* True when this window's recurring tail or single worst sample is an order of magnitude past
|
|
756
|
+
* its middle, which is a stall rather than a frame rate. A window with no p50 to compare against
|
|
757
|
+
* says nothing either way.
|
|
758
|
+
*/
|
|
759
|
+
#stalled(window: IScalerWindow): boolean {
|
|
760
|
+
const { max, p50, p99 } = window.presented;
|
|
761
|
+
if (!(p50 > 0) || !Number.isFinite(p99) || !Number.isFinite(max)) return false;
|
|
762
|
+
return (
|
|
763
|
+
p99 >= p50 * RESOLUTION_SCALER.stallP99Multiple ||
|
|
764
|
+
max >= p50 * RESOLUTION_SCALER.stallMaxMultiple
|
|
765
|
+
);
|
|
766
|
+
}
|
|
767
|
+
|
|
768
|
+
/**
|
|
769
|
+
* How many rungs one down-step should cross, from the fps deficit alone.
|
|
770
|
+
*
|
|
771
|
+
* Each rung is `0.72x` the pixels, so closing a deficit of `target / measured` needs
|
|
772
|
+
* `log(deficit) / log(1 / 0.72)` rungs if the whole frame scaled with pixels. It does not — but
|
|
773
|
+
* a single window cannot say how much of it does, and the up-step is there to give back what
|
|
774
|
+
* this takes too eagerly.
|
|
775
|
+
*/
|
|
776
|
+
#rungsToDrop(fps: number): number {
|
|
777
|
+
if (!(fps > 0)) return RESOLUTION_SCALER.maxDownRungs;
|
|
778
|
+
const deficit = this.targetFps / fps;
|
|
779
|
+
if (!(deficit > 1)) return 1;
|
|
780
|
+
const rungs = Math.ceil(Math.log(deficit) / Math.log(1 / RUNG_PIXEL_RATIO));
|
|
781
|
+
return Math.min(Math.max(1, rungs), RESOLUTION_SCALER.maxDownRungs);
|
|
782
|
+
}
|
|
783
|
+
|
|
784
|
+
#step(direction: number, countGuard = true): number {
|
|
785
|
+
// The boundary a fall from rung n crosses is the same one the climb back to n crosses.
|
|
786
|
+
const boundary = direction > 0 ? this.#index : this.#index - 1;
|
|
787
|
+
// The platform's floor is a limit, not a step count: a jump sized on a deficit can ask for
|
|
788
|
+
// more rungs than the floor allows, and it must land on the floor rather than past it.
|
|
789
|
+
const next = this.#index + direction;
|
|
790
|
+
this.#index = direction > 0 ? Math.min(next, this.#limitIndex) : Math.max(0, next);
|
|
791
|
+
this.#cooldown = RESOLUTION_SCALER.cooldownWindows;
|
|
792
|
+
// A refund is a measurement correction, not workload oscillation: counting it would let
|
|
793
|
+
// probe/refund cycles pin the scaler at a rung pixels were just proven not to earn.
|
|
794
|
+
if (countGuard) this.#noteForOscillationGuard(boundary, direction);
|
|
795
|
+
this.#continuousScale = RESOLUTION_SCALER.rungs[this.#index] ?? 1;
|
|
796
|
+
return this.scale;
|
|
797
|
+
}
|
|
798
|
+
|
|
799
|
+
#noteForOscillationGuard(boundary: number, direction: number): void {
|
|
800
|
+
const withinReach =
|
|
801
|
+
this.#windowIndex - this.#guardWindow <= RESOLUTION_SCALER.oscillationWindows;
|
|
802
|
+
const continues =
|
|
803
|
+
boundary === this.#guardBoundary && withinReach && direction !== this.#guardDirection;
|
|
804
|
+
this.#guardLegs = continues ? this.#guardLegs + 1 : 1;
|
|
805
|
+
this.#guardBoundary = boundary;
|
|
806
|
+
this.#guardDirection = direction;
|
|
807
|
+
this.#guardWindow = this.#windowIndex;
|
|
808
|
+
// down, up, down is one cycle. The next cycle reuses this leg as its first.
|
|
809
|
+
if (this.#guardLegs < 3) return;
|
|
810
|
+
this.#guardLegs = 1;
|
|
811
|
+
this.#guardCycles += 1;
|
|
812
|
+
if (this.#guardCycles < RESOLUTION_SCALER.oscillationCycles) return;
|
|
813
|
+
// Suppress upward probes temporarily; neither recovery nor later overload may be locked out
|
|
814
|
+
// for the rest of a session because the workload once sat near a thermal edge.
|
|
815
|
+
this.#index = Math.max(this.#index, boundary + 1);
|
|
816
|
+
this.#scaleSource = "auto-pinned";
|
|
817
|
+
this.#pinWindows = RESOLUTION_SCALER.oscillationWindows;
|
|
818
|
+
}
|
|
819
|
+
}
|