@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
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { Object3D, Matrix4, Camera } from 'three';
|
|
2
|
-
import { MRTNode, Node } from 'three/webgpu';
|
|
1
|
+
import { Vector2, Texture, RenderTarget, Object3D, Matrix4, Camera, BufferGeometry, DepthTexture } from 'three';
|
|
2
|
+
import { MRTNode, Node, StorageBufferAttribute, ReadbackBuffer } from 'three/webgpu';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Host-boundary counters, default-off, on the frame budget's own record.
|
|
@@ -26,11 +26,19 @@ import { MRTNode, Node } from 'three/webgpu';
|
|
|
26
26
|
* Wrapping every method of a command encoder is not free — it is one extra JS call per command, and
|
|
27
27
|
* this is why the counters ride the same opt-in flag as the spans rather than being always on.
|
|
28
28
|
*/
|
|
29
|
-
/**
|
|
29
|
+
/**
|
|
30
|
+
* One frame's boundary counts, plus the simulation tick it closed on.
|
|
31
|
+
*
|
|
32
|
+
* Every boundary field is absent when the platform cannot report it. `simulationTick` is not a
|
|
33
|
+
* platform reading: it is the loop's fixed-step count, absent when the caller fed none, and it
|
|
34
|
+
* rides here so a plain frame-budget window can be joined to the simulation without the spans flag.
|
|
35
|
+
*/
|
|
30
36
|
interface IFrameCounters {
|
|
31
37
|
readonly gpuBytes?: number;
|
|
32
38
|
readonly hostCalls?: number;
|
|
33
39
|
readonly jsAllocBytes?: number;
|
|
40
|
+
/** The loop's fixed-step count at the frame's end; absent when the caller did not feed one. */
|
|
41
|
+
readonly simulationTick?: number;
|
|
34
42
|
}
|
|
35
43
|
/** The slice of a WebGPU device this reads. Structural, so a test can stand in a fake. */
|
|
36
44
|
interface ICounterDevice {
|
|
@@ -74,17 +82,115 @@ declare class FrameCounters {
|
|
|
74
82
|
* Measurement, not policy: installing this alters no draw. `install` answers `undefined` on a
|
|
75
83
|
* renderer whose `info.render` cannot be read, and a consumer must then report the pass split as
|
|
76
84
|
* absent rather than zero.
|
|
85
|
+
*
|
|
86
|
+
* The main pass's own draws are also split by where their mesh came from, counted at the one place
|
|
87
|
+
* a draw is counted — `info.update`, which every backend calls per submitted draw with the object
|
|
88
|
+
* that owns it — so the sources sum to `draws` by construction instead of by an estimate beside it.
|
|
77
89
|
*/
|
|
78
90
|
/** The named kinds of a render pass. Closed on purpose: a consumer bounds a known kind. */
|
|
79
91
|
declare const FRAME_PASS_KINDS: readonly ["main", "shadow", "reflection", "nested"];
|
|
80
92
|
type FramePassKind = (typeof FRAME_PASS_KINDS)[number];
|
|
81
|
-
/**
|
|
93
|
+
/**
|
|
94
|
+
* Where a main-pass draw's mesh came from. Closed, and `other` is the default.
|
|
95
|
+
*
|
|
96
|
+
* Each entry is a system that owns its meshes and writes the origin on them, so the split reads as
|
|
97
|
+
* an answer about systems rather than about geometry: `gpuScene` and `bundles` are `WorldCells`' two
|
|
98
|
+
* ways of drawing one main batch (a GPU-dressed key, and the same mesh replayed from the world's
|
|
99
|
+
* bundle), `terrain` is every mesh `world-tiles.ts` creates, `proxies` is the shadow halves and the
|
|
100
|
+
* whole-map impostor aggregates, `chunks` is a hand-placed chunk's own draws, `instanced` is a main
|
|
101
|
+
* batch the GPU scene never dressed, and `sky` is a daylight rig's sky box. What is left in `other`
|
|
102
|
+
* is a mesh no world system claimed — a character, a prop, a water surface the game loaded — which is
|
|
103
|
+
* the bucket that has to be small enough to be worth naming one draw at a time.
|
|
104
|
+
*/
|
|
105
|
+
declare const MAIN_DRAW_SOURCES: readonly ["gpuScene", "bundles", "terrain", "proxies", "chunks", "instanced", "sky", "other"];
|
|
106
|
+
type MainDrawSource = (typeof MAIN_DRAW_SOURCES)[number];
|
|
107
|
+
/**
|
|
108
|
+
* One render call's own submissions, attributed to its innermost active render call.
|
|
109
|
+
*
|
|
110
|
+
* `drawsBySource` is `main`'s own draws by origin, in the frame's counts rather than in percentiles:
|
|
111
|
+
* it sums to `draws` for the frame, which is the claim the split exists to answer. Absent when the
|
|
112
|
+
* renderer named no object for one of those draws, because a split that guessed where a draw came
|
|
113
|
+
* from would read as a measurement.
|
|
114
|
+
*/
|
|
82
115
|
interface IRenderPassSample {
|
|
83
116
|
readonly draws: number;
|
|
117
|
+
readonly drawsBySource?: Readonly<Partial<Record<MainDrawSource, number>>>;
|
|
84
118
|
readonly kind: FramePassKind;
|
|
85
119
|
readonly triangles: number;
|
|
86
120
|
}
|
|
87
121
|
|
|
122
|
+
type PlatformRuntime = "web" | "native";
|
|
123
|
+
type PlatformOS = "android" | "ios" | "linux" | "macos" | "windows" | "unknown";
|
|
124
|
+
type PlatformFormFactor = "mobile" | "desktop" | "unknown";
|
|
125
|
+
interface IPlatformInfo {
|
|
126
|
+
readonly runtime: PlatformRuntime;
|
|
127
|
+
readonly os: PlatformOS;
|
|
128
|
+
readonly formFactor: PlatformFormFactor;
|
|
129
|
+
readonly maxTouchPoints: number;
|
|
130
|
+
}
|
|
131
|
+
declare function getPlatform(): Readonly<IPlatformInfo>;
|
|
132
|
+
declare function isWeb(): boolean;
|
|
133
|
+
declare function isNative(): boolean;
|
|
134
|
+
declare function isMobile(): boolean;
|
|
135
|
+
declare function isTouchscreenAvailable(): boolean;
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* One rule for what `display.maxFps` means when a game does not say.
|
|
139
|
+
*
|
|
140
|
+
* A template that shipped `maxFps: 60` taught every agent to copy the line, and every 120 Hz
|
|
141
|
+
* desktop then ran its game at half the panel it was sitting on — a default that is a constant the
|
|
142
|
+
* author is told to revisit later is a bug, not an option. So the default follows the display,
|
|
143
|
+
* capped at 120 on desktop and web, and stays 60 on mobile where the ceiling is power and heat
|
|
144
|
+
* rather than pixels. An explicit number still wins and `0` still removes the ceiling.
|
|
145
|
+
*
|
|
146
|
+
* **A browser has no refresh-rate API**, so "follows the display" is a measurement: the median
|
|
147
|
+
* interval between presented frames over the frame budget's first window is the panel's period,
|
|
148
|
+
* because on the web one rAF callback is one vblank. A native host says its own rate through the
|
|
149
|
+
* present counter, which is the only series there that counts displays rather than loop
|
|
150
|
+
* iterations. Both arrive as `measuredRefreshHz`; until one does, the answer is 60 and says so.
|
|
151
|
+
*/
|
|
152
|
+
|
|
153
|
+
/** What a game gets before anything has been measured, and all a mobile gets. */
|
|
154
|
+
declare const DEFAULT_TARGET_FPS = 60;
|
|
155
|
+
/** The desktop and web ceiling, whatever the panel runs at. */
|
|
156
|
+
declare const MAX_TARGET_FPS = 120;
|
|
157
|
+
/**
|
|
158
|
+
* Where a resolved target came from, so a harness can assert the *rule* and not just the number:
|
|
159
|
+
* `"config"` is the game naming it, `"display"` a measured panel rate, `"mobile-default"` the
|
|
160
|
+
* mobile power ceiling, and `"fallback"` the 60 held until a measurement exists. An unmeasured 60
|
|
161
|
+
* is not the display's rate and does not report as one.
|
|
162
|
+
*/
|
|
163
|
+
type TargetFpsSource = "config" | "display" | "fallback" | "mobile-default";
|
|
164
|
+
/** A resolved frame budget: the rate the loop holds, and what decided it. */
|
|
165
|
+
interface ITargetFps {
|
|
166
|
+
readonly targetFps: number;
|
|
167
|
+
readonly source: TargetFpsSource;
|
|
168
|
+
}
|
|
169
|
+
/** Whatever holds `display.maxFps` — `IGameConfig`, `IThreeNativeConfig`, or a bare object. */
|
|
170
|
+
interface ITargetFpsConfig {
|
|
171
|
+
readonly display?: {
|
|
172
|
+
readonly maxFps?: number | undefined;
|
|
173
|
+
} | undefined;
|
|
174
|
+
}
|
|
175
|
+
/** Only the one field the rule reads, so a caller need not hold a whole `IPlatformInfo`. */
|
|
176
|
+
type ITargetFpsPlatform = Pick<IPlatformInfo, "formFactor">;
|
|
177
|
+
/**
|
|
178
|
+
* The nearest common refresh rate, never above `MAX_TARGET_FPS`.
|
|
179
|
+
*
|
|
180
|
+
* A measured 59.94 Hz panel and a measured 60 Hz one are the same panel, and a value the engine
|
|
181
|
+
* invents rather than reads is a value no display can be asked to hold.
|
|
182
|
+
*/
|
|
183
|
+
declare function snapRefreshRate(refreshHz: number): number;
|
|
184
|
+
/**
|
|
185
|
+
* The single reader of `display.maxFps`, used by the loop, the resolution scaler, the scene-shape
|
|
186
|
+
* warning, the frame-budget marker and the templates.
|
|
187
|
+
*
|
|
188
|
+
* `measuredRefreshHz` is the display's own rate when the platform can say it, and is what turns
|
|
189
|
+
* `"fallback"` into `"display"`. A negative or non-finite configured rate throws rather than
|
|
190
|
+
* quietly falling back: a config the engine ignored is worse than a config it rejected.
|
|
191
|
+
*/
|
|
192
|
+
declare function resolveTargetFps(config: ITargetFpsConfig | undefined, platform: ITargetFpsPlatform | undefined, measuredRefreshHz?: number): ITargetFps;
|
|
193
|
+
|
|
88
194
|
/**
|
|
89
195
|
* Per-presented-frame cost attribution, on by default, for every platform.
|
|
90
196
|
*
|
|
@@ -142,6 +248,7 @@ interface IFramePhaseSample {
|
|
|
142
248
|
* convention off does not turn its measurement off.
|
|
143
249
|
*/
|
|
144
250
|
interface IFrameSurfaceState {
|
|
251
|
+
readonly resolutionSubrect?: boolean;
|
|
145
252
|
/** The applied drawing-buffer scale, in `(0, 1]`. */
|
|
146
253
|
readonly resolutionScale: number;
|
|
147
254
|
/**
|
|
@@ -173,15 +280,49 @@ interface IFrameBudgetSummary {
|
|
|
173
280
|
readonly p99: number;
|
|
174
281
|
readonly max: number;
|
|
175
282
|
}
|
|
283
|
+
/** Where one resolved frame's GPU milliseconds went. Closed on purpose, like the phases. */
|
|
284
|
+
declare const FRAME_GPU_BUCKETS: readonly ["main", "shadow", "other", "compute"];
|
|
285
|
+
type FrameGpuBucket = (typeof FRAME_GPU_BUCKETS)[number];
|
|
286
|
+
/** One frame's GPU milliseconds per bucket; a bucket the device did not resolve is absent. */
|
|
287
|
+
type IFrameGpuBucketSample = Partial<Record<FrameGpuBucket, number>> & {
|
|
288
|
+
/**
|
|
289
|
+
* Shadow passes the frame recorded, from the producer. `0` means the frame drew no shadow and its
|
|
290
|
+
* `shadow` bucket is a known zero; `> 0` means it rendered one. Absent when the source cannot say,
|
|
291
|
+
* and no frame is then counted as rendered.
|
|
292
|
+
*/
|
|
293
|
+
readonly shadowPasses?: number;
|
|
294
|
+
};
|
|
176
295
|
/**
|
|
177
296
|
* One render-pass kind's submissions across a window, so a change that trades triangles for CPU is
|
|
178
297
|
* visible in the same report as the milliseconds it traded for.
|
|
179
298
|
*/
|
|
180
299
|
interface IFrameBudgetPassSummary {
|
|
181
300
|
readonly draws: IFrameBudgetSummary;
|
|
301
|
+
/**
|
|
302
|
+
* The main pass's own draws per origin, summarised like every other series in this window.
|
|
303
|
+
*
|
|
304
|
+
* The per-frame counts sum to `draws` exactly, which is the invariant the split exists to answer;
|
|
305
|
+
* the percentiles below do not have to, because a source that draws on some frames and not others
|
|
306
|
+
* has a median over its own frames rather than over the window's. A source no frame drew is
|
|
307
|
+
* absent. Absent altogether — never a set of zeros — when the renderer named no object behind one
|
|
308
|
+
* of the pass's draws, which is the same rule the pass record itself follows. One exception to the
|
|
309
|
+
* sum: a world with bundles on counts its replays here, and three never traverses a replay, so the
|
|
310
|
+
* sources can exceed `draws`; the sum holds for the sources that went through the per-draw path.
|
|
311
|
+
*/
|
|
312
|
+
readonly drawsBySource?: Readonly<Partial<Record<MainDrawSource, IFrameBudgetSummary>>>;
|
|
182
313
|
/** Frames in the window that submitted a pass of this kind. */
|
|
183
314
|
readonly frames: number;
|
|
315
|
+
/**
|
|
316
|
+
* Three's CPU figure: `instanceCount * count / 3` per draw, where an indirect batch's `count` is
|
|
317
|
+
* the merged geometry's capacity. An upper bound over what the GPU could select.
|
|
318
|
+
*/
|
|
184
319
|
readonly triangles: IFrameBudgetSummary;
|
|
320
|
+
/**
|
|
321
|
+
* What the GPU selected, main pass only: the streamed world's own indirect tally, beside the
|
|
322
|
+
* figure above so a reader of the pass record can tell which of the two it is holding. Absent
|
|
323
|
+
* rather than zero when the world reported no tally — see `mainGpuTriangles`.
|
|
324
|
+
*/
|
|
325
|
+
readonly gpuTriangles?: number;
|
|
185
326
|
}
|
|
186
327
|
/**
|
|
187
328
|
* One reported window of the frame meter.
|
|
@@ -198,10 +339,21 @@ interface IFrameBudgetPassSummary {
|
|
|
198
339
|
* it were a player's — `threenative-playtest perf` refuses to (`TN_PERF_VIRTUAL_DISPLAY`).
|
|
199
340
|
*/
|
|
200
341
|
interface IFrameBudgetWindow {
|
|
342
|
+
/** Browser Long Tasks, independent of vsync/GPU waits. Unavailable on hosts without this API. */
|
|
343
|
+
readonly longTasks: {
|
|
344
|
+
readonly available: false;
|
|
345
|
+
} | {
|
|
346
|
+
readonly available: true;
|
|
347
|
+
readonly count: number;
|
|
348
|
+
readonly longestMs: number;
|
|
349
|
+
readonly afterFirstFrameMs: number;
|
|
350
|
+
};
|
|
201
351
|
/** 1 for the first reported window, incrementing thereafter. */
|
|
202
352
|
readonly window: number;
|
|
203
353
|
/** Loop frames counted in this window, hitches excluded — one per present on the web. */
|
|
204
354
|
readonly frames: number;
|
|
355
|
+
/** Fixed simulation ticks in this window multiplied by the loop's step, when supplied. */
|
|
356
|
+
readonly simulatedSeconds?: number;
|
|
205
357
|
/** Frames excluded from the window because their present gap exceeded `hitchMs`. */
|
|
206
358
|
readonly hitches: number;
|
|
207
359
|
/**
|
|
@@ -241,12 +393,45 @@ interface IFrameBudgetWindow {
|
|
|
241
393
|
* is absent; `frames` says how many frames did.
|
|
242
394
|
*/
|
|
243
395
|
readonly passes?: Readonly<Partial<Record<FramePassKind, IFrameBudgetPassSummary>>>;
|
|
396
|
+
/**
|
|
397
|
+
* Instances and triangles the GPU actually selected in the main pass, from the streamed world's
|
|
398
|
+
* own indirect-args tally when it has one.
|
|
399
|
+
*
|
|
400
|
+
* These are the honest counterpart of `passes.main`: three's `renderer.info.render.triangles`
|
|
401
|
+
* counts a mesh's CPU window/capacity for an indirect draw, so `passes.main.triangles` is an upper
|
|
402
|
+
* bound over what the GPU could draw, while `mainGpuTriangles` is the sum over the indirect
|
|
403
|
+
* records of `instanceCount x indexCount / 3` — what the kernel selected. Main pass only: shadow
|
|
404
|
+
* passes are not tallied. Absent, never zero, before the first sample lands.
|
|
405
|
+
*/
|
|
406
|
+
readonly mainGpuInstances?: number;
|
|
407
|
+
readonly mainGpuTriangles?: number;
|
|
244
408
|
/**
|
|
245
409
|
* The resolution and sampling this window's frames were drawn at, when the loop reported one.
|
|
246
410
|
* Absent rather than defaulted: a consumer asserting on it must fail loudly instead of reading
|
|
247
411
|
* a fabricated `1.0` that no frame was ever drawn at.
|
|
248
412
|
*/
|
|
249
413
|
readonly surface?: IFrameSurfaceState;
|
|
414
|
+
/**
|
|
415
|
+
* The rate the loop is holding, and what decided it, when the engine resolved one.
|
|
416
|
+
*
|
|
417
|
+
* Two fields rather than an object, and a harness reads them without unwrapping anything: a
|
|
418
|
+
* number nobody can place (`targetSource: "fallback"`) is the difference between a game holding
|
|
419
|
+
* its panel and a game settling for 60, and only this line says which one happened.
|
|
420
|
+
*/
|
|
421
|
+
readonly targetFps?: number;
|
|
422
|
+
readonly targetSource?: TargetFpsSource;
|
|
423
|
+
/**
|
|
424
|
+
* Frames in this window that ran past the target frame (`1000 / targetFps`, the target this
|
|
425
|
+
* window started with): `render` over every counted frame's render phase, `gpu` over the frames
|
|
426
|
+
* with a resolved GPU sample. A pooled p95 is under the target exactly when at most 5 % of the
|
|
427
|
+
* pooled frames are, which window quantiles can only bound (PRD-478). Absent until a target is
|
|
428
|
+
* known.
|
|
429
|
+
*/
|
|
430
|
+
readonly overTarget?: {
|
|
431
|
+
readonly frameMs: number;
|
|
432
|
+
readonly gpu: number;
|
|
433
|
+
readonly render: number;
|
|
434
|
+
};
|
|
250
435
|
/**
|
|
251
436
|
* GPU milliseconds per resolved frame in this window, from `timestamp-query`, summarised like a
|
|
252
437
|
* phase — mean/p50/p95/p99/max over the frames the device actually reported.
|
|
@@ -264,6 +449,13 @@ interface IFrameBudgetWindow {
|
|
|
264
449
|
* every frame is stale reports `gpu` absent rather than the last reading looking current.
|
|
265
450
|
*/
|
|
266
451
|
readonly gpuStale: number;
|
|
452
|
+
/**
|
|
453
|
+
* Frames in the window the renderer declined to draw (the Wasm web engine holds at most two drawn
|
|
454
|
+
* frames on the GPU). Their render phase is near zero, so `phases.render` over the window reads
|
|
455
|
+
* cheaper than the frames that were drawn; divide by `frames - renderSkips` for a drawn frame's cost.
|
|
456
|
+
* Absent, not zero, when the renderer drew every frame.
|
|
457
|
+
*/
|
|
458
|
+
readonly renderSkips?: number;
|
|
267
459
|
/**
|
|
268
460
|
* The window mean of `gpu`, when present. The scalar the resolution scaler reads.
|
|
269
461
|
*
|
|
@@ -271,30 +463,79 @@ interface IFrameBudgetWindow {
|
|
|
271
463
|
* one series rather than a second instantaneous read.
|
|
272
464
|
*/
|
|
273
465
|
readonly gpuMs?: number;
|
|
466
|
+
/** Resolved renderer-frame range behind this window; unavailable for unframed samples. */
|
|
467
|
+
readonly gpuFrames?: {
|
|
468
|
+
readonly first: number;
|
|
469
|
+
readonly last: number;
|
|
470
|
+
};
|
|
274
471
|
/** Age of the most recent resolved GPU timestamp in Three.js frame IDs; absent means unobservable. */
|
|
275
472
|
readonly gpuAgeFrames?: number;
|
|
276
473
|
/**
|
|
277
|
-
*
|
|
474
|
+
* GPU milliseconds per resolved frame, split by where the device spent them: the main scene
|
|
475
|
+
* pass, every shadow pass, everything else in the render pool (post chain, reflections, HUD) and
|
|
476
|
+
* the compute pool. Each is the window's p50 over the frames that resolved it, one decimal.
|
|
477
|
+
*
|
|
478
|
+
* `gpu` is their sum's series; these say which pass owns it. Absent rather than zero when that
|
|
479
|
+
* bucket never resolved — an unmeasured pass and a free one are different facts — so
|
|
480
|
+
* `gpuMain + gpuShadow + gpuOther` reconciles with `gpuMs` only when all three are present.
|
|
481
|
+
*/
|
|
482
|
+
readonly gpuMain?: number;
|
|
483
|
+
readonly gpuShadow?: number;
|
|
484
|
+
readonly gpuOther?: number;
|
|
485
|
+
readonly gpuCompute?: number;
|
|
486
|
+
/**
|
|
487
|
+
* The shadow bucket's p95 and coverage over **every** frame that resolved a shadow reading,
|
|
488
|
+
* known-zero frames included, so the p95 can sit at zero while the shadow renders are expensive.
|
|
489
|
+
* Kept for compatibility beside {@link gpuShadowRendered}, which is the same tail over the frames
|
|
490
|
+
* that actually rendered a shadow — the distribution the phase comparison should read.
|
|
491
|
+
*/
|
|
492
|
+
readonly gpuShadowP95?: number;
|
|
493
|
+
readonly gpuShadowSamples?: number;
|
|
494
|
+
/**
|
|
495
|
+
* The shadow bucket's distribution over the frames that **actually rendered a shadow**, distinct
|
|
496
|
+
* from the known-zero frames the p50 and all-frame p95 above include.
|
|
497
|
+
*
|
|
498
|
+
* `samples` is how many frames rendered one, so observed renders are tellable from frames that
|
|
499
|
+
* drew none (`gpuShadowSamples - gpuShadowRendered.samples`). Absent, never a zeroed summary, when
|
|
500
|
+
* no rendered shadow resolved: a render that cost 0 ms is still a render, and only the producer's
|
|
501
|
+
* own `shadowPasses` record says one happened, so the count is not guessed from `shadow > 0`.
|
|
502
|
+
*/
|
|
503
|
+
readonly gpuShadowRendered?: IFrameBudgetSummary;
|
|
504
|
+
/** Pyramid build GPU milliseconds per resolved build, including the depth copy/resolve. */
|
|
505
|
+
readonly gpuPyramid?: IFrameBudgetSummary;
|
|
506
|
+
/**
|
|
507
|
+
* The frame's boundary counts, when something counted them, plus the simulation tick the window
|
|
508
|
+
* closed on when the loop fed one.
|
|
278
509
|
*
|
|
279
|
-
* Each series is absent when nothing measured it, and a series present with zero samples
|
|
280
|
-
* possible: an uncounted frame and a frame that crossed the boundary zero times are
|
|
281
|
-
* facts, and a fabricated zero merges them. `hostCalls` and `gpuBytes` come from
|
|
510
|
+
* Each boundary series is absent when nothing measured it, and a series present with zero samples
|
|
511
|
+
* is not possible: an uncounted frame and a frame that crossed the boundary zero times are
|
|
512
|
+
* different facts, and a fabricated zero merges them. `hostCalls` and `gpuBytes` come from
|
|
282
513
|
* `FrameCounters`; `jsAllocBytes` needs a platform that publishes `performance.memory`.
|
|
514
|
+
* `simulationTick` is not a platform reading — it is the loop's latest fixed-step count, so the
|
|
515
|
+
* object is present whenever `addCounters` carried a tick even with no boundary field measured.
|
|
283
516
|
*/
|
|
284
517
|
readonly counters?: {
|
|
285
518
|
readonly hostCalls?: IFrameBudgetSummary;
|
|
286
519
|
readonly gpuBytes?: IFrameBudgetSummary;
|
|
287
520
|
readonly jsAllocBytes?: IFrameBudgetSummary;
|
|
521
|
+
readonly simulationTick?: number;
|
|
288
522
|
};
|
|
289
523
|
}
|
|
524
|
+
interface IFrameBudgetSimulation {
|
|
525
|
+
readonly tick: () => number;
|
|
526
|
+
readonly step: number;
|
|
527
|
+
}
|
|
290
528
|
interface IFrameBudgetOptions {
|
|
291
|
-
/**
|
|
529
|
+
/** Simulation ticks per report window when a clock is supplied, otherwise presented frames. Default 300. */
|
|
292
530
|
readonly reportEvery?: number;
|
|
531
|
+
/** Minimum measured rendered frames per report window. Default 1. */
|
|
532
|
+
readonly minFrames?: number;
|
|
533
|
+
readonly simulation?: IFrameBudgetSimulation;
|
|
293
534
|
/** A present gap at or above this is a hitch, not a frame. Default 2000 ms. */
|
|
294
535
|
readonly hitchMs?: number;
|
|
295
536
|
/** Ring capacity per series. Default 1024. */
|
|
296
537
|
readonly capacity?: number;
|
|
297
|
-
/** Where marker lines go. Default `console.log`. */
|
|
538
|
+
/** Where marker lines go. Default `console.log`. In defineGame, also receives all window telemetry; without a custom sink its existing info/warn severities remain. */
|
|
298
539
|
readonly report?: (line: string) => void;
|
|
299
540
|
/** Wall clock for hitch markers. Default `Date.now`. */
|
|
300
541
|
readonly wallClock?: () => number;
|
|
@@ -309,6 +550,13 @@ interface IFrameBudgetOptions {
|
|
|
309
550
|
* loop, which is the only place that knows both the renderer and the window boundary.
|
|
310
551
|
*/
|
|
311
552
|
readonly readSurface?: () => IFrameSurfaceState;
|
|
553
|
+
/**
|
|
554
|
+
* The engine's resolved frame budget, read once per reported window.
|
|
555
|
+
*
|
|
556
|
+
* Wired by the game, which owns the rule and the panel measurement behind it. A window with no
|
|
557
|
+
* resolver reports no target rather than a default that looks measured.
|
|
558
|
+
*/
|
|
559
|
+
readonly readTarget?: () => ITargetFps | undefined;
|
|
312
560
|
/**
|
|
313
561
|
* Frames the display has presented so far, when the platform can say.
|
|
314
562
|
*
|
|
@@ -319,17 +567,29 @@ interface IFrameBudgetOptions {
|
|
|
319
567
|
readonly readPresentCount?: () => number | undefined;
|
|
320
568
|
/** Reads the successful GPU query frame age, not the age of the last resolve attempt. */
|
|
321
569
|
readonly readGpuAgeFrames?: () => number | undefined;
|
|
570
|
+
/**
|
|
571
|
+
* The GPU-selected main-pass instance and triangle count, read once per reported window.
|
|
572
|
+
*
|
|
573
|
+
* Wired by the game from the streamed world's own tally; `undefined` until its first sample lands
|
|
574
|
+
* or when the world has none, so a window reports absent rather than a fabricated zero.
|
|
575
|
+
*/
|
|
576
|
+
readonly readGpuTally?: () => {
|
|
577
|
+
readonly instances: number;
|
|
578
|
+
readonly triangles: number;
|
|
579
|
+
} | undefined;
|
|
322
580
|
}
|
|
323
581
|
/**
|
|
324
582
|
* Accumulates one frame at a time and reports windowed attribution.
|
|
325
583
|
*
|
|
326
584
|
* The caller is the frame loop; the sequence per frame is
|
|
327
585
|
* `beginFrame` → `markSimulationEnd` → (`addRender` / `addOverlay` / `addUi`) → `endFrame`.
|
|
328
|
-
* Calling them out of order throws rather than producing a plausible-looking split.
|
|
586
|
+
* Calling them out of order throws rather than producing a plausible-looking split. The one
|
|
587
|
+
* exception is `addSimulation`, which reports simulation that ran outside any frame — see it.
|
|
329
588
|
*/
|
|
330
589
|
declare class FrameBudget {
|
|
331
590
|
#private;
|
|
332
591
|
readonly reportEvery: number;
|
|
592
|
+
readonly minFrames: number;
|
|
333
593
|
readonly hitchMs: number;
|
|
334
594
|
constructor(options?: IFrameBudgetOptions);
|
|
335
595
|
/**
|
|
@@ -337,10 +597,31 @@ declare class FrameBudget {
|
|
|
337
597
|
* clock, which is not the same as `nowMs` and is what the interval between frames comes from.
|
|
338
598
|
* @param nowMs the monotonic clock at callback entry.
|
|
339
599
|
*/
|
|
600
|
+
dispose(): void;
|
|
340
601
|
beginFrame(timestampMs: number, nowMs: number): void;
|
|
341
602
|
/** The boundary between the fixed-step simulation and everything the render phase does. */
|
|
342
603
|
markSimulationEnd(nowMs: number, substeps: number): void;
|
|
604
|
+
/**
|
|
605
|
+
* Charges one counted simulation batch — the loop's `advance(ticks)`, which is how a tick-counted
|
|
606
|
+
* playtest run simulates at all — to this window's `update` and `substeps`.
|
|
607
|
+
*
|
|
608
|
+
* A batch is not a frame. It presents nothing, so it must not count as one: no frame in the
|
|
609
|
+
* window, no present interval, no GPU sample, no hitch however long it blocked, and no window
|
|
610
|
+
* boundary. Opening a metered frame around it instead put half of a fixed-step run's windows into
|
|
611
|
+
* the frame and render percentiles as zero-millisecond frames that drew nothing, and closed a
|
|
612
|
+
* "300-frame" window on 300 metered frames rather than 300 presented ones — which is how a
|
|
613
|
+
* 300-frame window came to hold ~20 GPU timestamp samples instead of ~37.
|
|
614
|
+
*
|
|
615
|
+
* Inside a live frame — the frozen prime's settle, which is `advance()` called from inside the
|
|
616
|
+
* frame that armed it — the batch's milliseconds are already inside that frame's own measurement
|
|
617
|
+
* and are not charged a second time; only its steps are added, so the frame reports it exactly
|
|
618
|
+
* once. Its blocking cost reaches the window either way: through the enclosing frame's `update`,
|
|
619
|
+
* or here.
|
|
620
|
+
*/
|
|
621
|
+
addSimulation(ms: number, ticks: number): void;
|
|
343
622
|
addRender(ms: number): void;
|
|
623
|
+
/** The renderer returned without drawing this frame; counted once per frame in the window's `renderSkips`. */
|
|
624
|
+
addRenderSkip(): void;
|
|
344
625
|
addOverlay(ms: number): void;
|
|
345
626
|
addUi(ms: number): void;
|
|
346
627
|
/**
|
|
@@ -356,12 +637,27 @@ declare class FrameBudget {
|
|
|
356
637
|
* Once per frame. A window with no reading at all reports `gpu` absent, never a zero.
|
|
357
638
|
*/
|
|
358
639
|
addGpuMs(ms: number | undefined, frame?: number): void;
|
|
640
|
+
/** Record one freshly resolved pyramid build, independently of the render pool's cadence. */
|
|
641
|
+
addGpuPyramidMs(ms: number | undefined): void;
|
|
642
|
+
/**
|
|
643
|
+
* Records where one resolved frame's GPU time went, from the per-pass timestamp split.
|
|
644
|
+
*
|
|
645
|
+
* Alongside `addGpuMs`, once per frame. A bucket the producer could not attribute is left out
|
|
646
|
+
* rather than passed as zero: an unmeasured pass and a free one are different facts, and the
|
|
647
|
+
* p50 of a bucket that was never measured is absent from the window. An unknown bucket name
|
|
648
|
+
* throws rather than being dropped, the same fail-closed rule as a phase.
|
|
649
|
+
*/
|
|
650
|
+
addGpuBucketMs(sample: IFrameGpuBucketSample): void;
|
|
359
651
|
/**
|
|
360
652
|
* Records the frame's host-boundary counts, from `FrameCounters` or any other source.
|
|
361
653
|
*
|
|
362
654
|
* At most one call per frame; a second replaces the first rather than summing, because the
|
|
363
655
|
* counter's own reader already returns the frame's totals and summing two reads of one frame
|
|
364
656
|
* would double it. A field the platform cannot report is left out of the series entirely.
|
|
657
|
+
*
|
|
658
|
+
* `simulationTick`, when present, must be a finite non-negative integer and is stored as the
|
|
659
|
+
* window's latest tick — never summed, and never cleared by a later call that omits it, so a
|
|
660
|
+
* plain `TN_FRAME_BUDGET` log can join a window's start and end ticks.
|
|
365
661
|
*/
|
|
366
662
|
addCounters(counters: IFrameCounters): void;
|
|
367
663
|
/**
|
|
@@ -463,8 +759,22 @@ interface IPipelineCensusEvent {
|
|
|
463
759
|
/** Promise latency is retained as latency, never labelled native compiler time. */
|
|
464
760
|
readonly promiseMs?: number;
|
|
465
761
|
readonly error?: string;
|
|
762
|
+
/** Number of distinct Three node-builder states first observed during this render-object call. */
|
|
763
|
+
readonly nodeBuilds?: number;
|
|
466
764
|
/** Whether this event settled before the first present boundary. */
|
|
467
765
|
readonly beforeFirstPresent?: boolean;
|
|
766
|
+
/** Whether this event settled before the explicit warm-up completion boundary. */
|
|
767
|
+
readonly beforeWarmUpSettled?: boolean;
|
|
768
|
+
/** The most recent streamed warm-up scope that preceded this event. */
|
|
769
|
+
readonly afterWarmUpScope?: string;
|
|
770
|
+
}
|
|
771
|
+
/** A node-builder state observed even when Three reused an existing GPU pipeline. */
|
|
772
|
+
interface IPipelineNodeBuild {
|
|
773
|
+
readonly provenance: IPipelineProvenance;
|
|
774
|
+
readonly startedMs: number;
|
|
775
|
+
readonly beforeFirstPresent?: boolean;
|
|
776
|
+
readonly beforeWarmUpSettled?: boolean;
|
|
777
|
+
readonly afterWarmUpScope?: string;
|
|
468
778
|
}
|
|
469
779
|
interface IPipelineCensusCounts {
|
|
470
780
|
readonly lookups: number;
|
|
@@ -475,6 +785,7 @@ interface IPipelineCensusCounts {
|
|
|
475
785
|
readonly uniquePipelines: number;
|
|
476
786
|
readonly recordedEvents: number;
|
|
477
787
|
readonly droppedEvents: number;
|
|
788
|
+
readonly nodeBuilds: number;
|
|
478
789
|
/**
|
|
479
790
|
* Every creation seen at the device, including those attributed to a backend event. Absent
|
|
480
791
|
* when the device could not be observed at all, so no reader mistakes silence for zero.
|
|
@@ -508,8 +819,26 @@ interface IPipelineCensus {
|
|
|
508
819
|
readonly boundaryMs: number;
|
|
509
820
|
readonly eventsSettled: number;
|
|
510
821
|
};
|
|
822
|
+
readonly warmUpSettled?: {
|
|
823
|
+
readonly boundaryMs: number;
|
|
824
|
+
readonly eventsSettled: number;
|
|
825
|
+
readonly nodeBuilds: number;
|
|
826
|
+
readonly renderPipelineCreations: number;
|
|
827
|
+
};
|
|
828
|
+
readonly warmUpScopes?: readonly {
|
|
829
|
+
readonly label: string;
|
|
830
|
+
readonly boundaryMs: number;
|
|
831
|
+
readonly eventsSettled: number;
|
|
832
|
+
readonly nodeBuilds: number;
|
|
833
|
+
readonly renderPipelineCreations: number;
|
|
834
|
+
readonly firstDraw?: {
|
|
835
|
+
readonly nodeBuilds: number;
|
|
836
|
+
readonly renderPipelineCreations: number;
|
|
837
|
+
};
|
|
838
|
+
}[];
|
|
511
839
|
readonly counts: IPipelineCensusCounts;
|
|
512
840
|
readonly events: readonly IPipelineCensusEvent[];
|
|
841
|
+
readonly nodeBuilds?: readonly IPipelineNodeBuild[];
|
|
513
842
|
readonly incompleteReasons: readonly string[];
|
|
514
843
|
}
|
|
515
844
|
interface IPipelineCensusOptions {
|
|
@@ -523,11 +852,14 @@ interface IPipelineCensusOptions {
|
|
|
523
852
|
}
|
|
524
853
|
interface IRendererHookTarget {
|
|
525
854
|
backend?: unknown;
|
|
855
|
+
/** Three's renderer-owned node manager; absent on the WebGL2 renderer. */
|
|
856
|
+
_nodes?: unknown;
|
|
526
857
|
renderObject?: (...args: unknown[]) => unknown;
|
|
527
858
|
}
|
|
528
859
|
/**
|
|
529
860
|
* Create and install a bounded census. The returned object is intentionally small: renderers own
|
|
530
|
-
* lifecycle and callers only need `snapshot()`, `withRenderObject()`, and
|
|
861
|
+
* lifecycle and callers only need `snapshot()`, `withRenderObject()`, and the two lifecycle
|
|
862
|
+
* boundaries.
|
|
531
863
|
*/
|
|
532
864
|
declare function createPipelineCensus(options: IPipelineCensusOptions): PipelineCensus;
|
|
533
865
|
declare class PipelineCensus {
|
|
@@ -541,11 +873,110 @@ declare class PipelineCensus {
|
|
|
541
873
|
dispose(): void;
|
|
542
874
|
/** Wrap Three's public render-object method so compileAsync retains the authored pass id. */
|
|
543
875
|
withRenderObject<T>(args: readonly unknown[], callback: () => T): T;
|
|
876
|
+
/** Begin the outer world render that can close target-bound streamed warm-up scopes. */
|
|
877
|
+
beginWorldFrame(root: object): void;
|
|
878
|
+
/** Close target-bound scopes only after the complete visible world frame has returned. */
|
|
879
|
+
endWorldFrame(root: object, completed: boolean): void;
|
|
544
880
|
/** Mark the first renderer render call as the first-present boundary. */
|
|
545
881
|
firstPresent(): void;
|
|
882
|
+
/** Mark the explicit shader warm-up as settled before the first measured world pass. */
|
|
883
|
+
warmUpSettled(): void;
|
|
884
|
+
/** Mark one repeatable streamed warm-up boundary; target-bound scopes close on their first world frame. */
|
|
885
|
+
warmUpScopeSettled(label: string, target?: object): void;
|
|
546
886
|
snapshot(): IPipelineCensus;
|
|
547
887
|
}
|
|
548
888
|
|
|
889
|
+
/** Exact per-call timings from Three 0.185.1's compute pool; Three owns all GPU resources. */
|
|
890
|
+
interface IComputeTimingSample {
|
|
891
|
+
readonly call: number;
|
|
892
|
+
readonly uid: string;
|
|
893
|
+
readonly gpuMs: number;
|
|
894
|
+
}
|
|
895
|
+
interface IComputeTimingReceipt {
|
|
896
|
+
readonly generation: object;
|
|
897
|
+
readonly calls: readonly number[];
|
|
898
|
+
/** Incomplete membership is absent; a completed receipt can be consumed only once. */
|
|
899
|
+
read(): readonly IComputeTimingSample[] | undefined;
|
|
900
|
+
}
|
|
901
|
+
|
|
902
|
+
/**
|
|
903
|
+
* Which family of GPU the adapter is: the start point of the look and of the pixel count.
|
|
904
|
+
*
|
|
905
|
+
* A fact about the machine, read from the four `adapter.info` fields and nothing else. What a
|
|
906
|
+
* class *looks like* is the game's own decision (`src/render/quality.ts`); this file only names the
|
|
907
|
+
* class, so a Mali-G52 phone and a Mali-G715 phone stop sharing one `mobile` flag.
|
|
908
|
+
*
|
|
909
|
+
* Measurement outranks this table. The first eligible frame-budget window moves the tier and the
|
|
910
|
+
* scale whichever class started them, so a wrong row costs windows, never a stuck look.
|
|
911
|
+
*/
|
|
912
|
+
type GpuClass = "software" | "mobile-low" | "mobile-mid" | "mobile-high" | "integrated" | "discrete" | "unknown";
|
|
913
|
+
/** The four fields WebGPU's `adapter.info` carries. A field the platform omits is the empty string. */
|
|
914
|
+
interface IGpuAdapterFields {
|
|
915
|
+
readonly architecture: string;
|
|
916
|
+
readonly description: string;
|
|
917
|
+
readonly device: string;
|
|
918
|
+
readonly vendor: string;
|
|
919
|
+
}
|
|
920
|
+
interface IGpuClassification {
|
|
921
|
+
readonly class: GpuClass;
|
|
922
|
+
/** The first rule that matched, or `none` when no rule did. */
|
|
923
|
+
readonly rule: string;
|
|
924
|
+
readonly fields: IGpuAdapterFields;
|
|
925
|
+
}
|
|
926
|
+
|
|
927
|
+
interface IGpuFrameObservationOptions {
|
|
928
|
+
readonly maxFrames: number;
|
|
929
|
+
/** Timestamp slots, two per allocated pass; bounds pending plus queued observations. */
|
|
930
|
+
readonly maxQueries: number;
|
|
931
|
+
}
|
|
932
|
+
interface IGpuObservedQuery {
|
|
933
|
+
readonly uid: string;
|
|
934
|
+
readonly begin: number;
|
|
935
|
+
readonly end: number;
|
|
936
|
+
readonly ms: number;
|
|
937
|
+
}
|
|
938
|
+
interface IGpuObservedFrame {
|
|
939
|
+
readonly generation: number;
|
|
940
|
+
readonly batch: number;
|
|
941
|
+
/** Three render-query frame, which may belong to an overlay; not a world callback ID. */
|
|
942
|
+
readonly frame: number;
|
|
943
|
+
readonly ms: number;
|
|
944
|
+
readonly queries: readonly IGpuObservedQuery[];
|
|
945
|
+
}
|
|
946
|
+
interface IGpuFrameObservationStatus {
|
|
947
|
+
readonly generation: number;
|
|
948
|
+
readonly state: "active" | "stopped" | "failed" | "disposed";
|
|
949
|
+
readonly stopFrame: number | undefined;
|
|
950
|
+
readonly maxFrames: number;
|
|
951
|
+
readonly maxQueries: number;
|
|
952
|
+
readonly expectedFrames: number;
|
|
953
|
+
readonly expectedQueries: number;
|
|
954
|
+
readonly resolvedFrames: number;
|
|
955
|
+
readonly resolvedQueries: number;
|
|
956
|
+
readonly deliveredFrames: number;
|
|
957
|
+
readonly deliveredQueries: number;
|
|
958
|
+
readonly pendingFrames: number;
|
|
959
|
+
readonly pendingQueries: number;
|
|
960
|
+
/** Eligible allocated membership waiting behind an older resolve; included in capacity. */
|
|
961
|
+
readonly undrainedFrames: number;
|
|
962
|
+
readonly undrainedQueries: number;
|
|
963
|
+
readonly queuedFrames: number;
|
|
964
|
+
readonly queuedQueries: number;
|
|
965
|
+
readonly droppedFrames: number;
|
|
966
|
+
readonly droppedQueries: number;
|
|
967
|
+
/** Allocation attempts are not instrumented. Saturation cannot prove zero lost queries. */
|
|
968
|
+
readonly allocationLoss: "not-observed" | "unknown-after-saturation";
|
|
969
|
+
readonly ignoredCompletions: number;
|
|
970
|
+
readonly failure: string | undefined;
|
|
971
|
+
}
|
|
972
|
+
interface IGpuFrameObservation {
|
|
973
|
+
take(): readonly IGpuObservedFrame[];
|
|
974
|
+
status(): IGpuFrameObservationStatus;
|
|
975
|
+
/** Fence selection now; existing renderer resolves continue draining eligible older frames. */
|
|
976
|
+
stop(): void;
|
|
977
|
+
dispose(): void;
|
|
978
|
+
}
|
|
979
|
+
|
|
549
980
|
/** The marker shared by alpha-antialiasing logs, playtests, and native diagnostics. */
|
|
550
981
|
declare const ALPHA_ANTIALIASING_MARKER = "TN_ALPHA_ANTIALIASING";
|
|
551
982
|
interface IAlphaAntialiasingReport {
|
|
@@ -560,6 +991,27 @@ interface IAlphaAntialiasingReport {
|
|
|
560
991
|
readonly materials: number;
|
|
561
992
|
}
|
|
562
993
|
|
|
994
|
+
interface IResolutionTextureView {
|
|
995
|
+
readonly viewFraction: Vector2;
|
|
996
|
+
readonly halfTexel: Vector2;
|
|
997
|
+
}
|
|
998
|
+
interface IResolutionSubrectNode {
|
|
999
|
+
setSize(width: number, height: number): void;
|
|
1000
|
+
}
|
|
1001
|
+
/** Owns capacity and viewport lifetime; generated render source owns sampling. */
|
|
1002
|
+
interface IResolutionSubrect {
|
|
1003
|
+
readonly active?: boolean;
|
|
1004
|
+
readonly view?: IResolutionTextureView;
|
|
1005
|
+
textureView(texture: Texture): IResolutionTextureView | undefined;
|
|
1006
|
+
activate?(scale: number): void;
|
|
1007
|
+
deactivate?(): void;
|
|
1008
|
+
setScale?(scale: number): void;
|
|
1009
|
+
setSize?(width: number, height: number): void;
|
|
1010
|
+
retain(node: IResolutionSubrectNode, targets: readonly RenderTarget[]): void;
|
|
1011
|
+
release(node: IResolutionSubrectNode): void;
|
|
1012
|
+
dispose(): void;
|
|
1013
|
+
}
|
|
1014
|
+
|
|
563
1015
|
/** The output name shared by the scene pass and temporal consumers. */
|
|
564
1016
|
declare const VELOCITY_OUTPUT_NAME = "velocity";
|
|
565
1017
|
/**
|
|
@@ -569,6 +1021,8 @@ declare const VELOCITY_OUTPUT_NAME = "velocity";
|
|
|
569
1021
|
* without making the game depend on either implementation.
|
|
570
1022
|
*/
|
|
571
1023
|
interface IVelocityRenderPass {
|
|
1024
|
+
/** Physical attachments on Three passes; structural adapters may own them elsewhere. */
|
|
1025
|
+
readonly renderTarget?: Pick<RenderTarget, "textures" | "dispose">;
|
|
572
1026
|
getMRT(): MRTNode | null;
|
|
573
1027
|
getTextureNode(name?: string): Node;
|
|
574
1028
|
setMRT(value: MRTNode | null): unknown;
|
|
@@ -599,6 +1053,17 @@ declare function velocityTexture(pass: IVelocityRenderPass): Node;
|
|
|
599
1053
|
* @situation hand the provisioned velocity source through a composed temporal graph
|
|
600
1054
|
*/
|
|
601
1055
|
declare function withVelocityContext<T>(node: T, source: Node): T;
|
|
1056
|
+
/**
|
|
1057
|
+
* How the render chain provisions the MRT velocity a temporal stage reads. The chain defaults to
|
|
1058
|
+
* {@link mrtVelocity}; a host that provisions velocity another way (an engine whose scene pass owns
|
|
1059
|
+
* the output) passes its own as `request.velocity.provision`.
|
|
1060
|
+
*/
|
|
1061
|
+
interface IVelocityProvision {
|
|
1062
|
+
/** Ensures `pass` writes velocity and returns its texture node. */
|
|
1063
|
+
texture(pass: IVelocityRenderPass): Node;
|
|
1064
|
+
/** Hands the velocity source through the composed graph; `source` is the node `texture` returned. */
|
|
1065
|
+
attach<T>(node: T, source: Node): T;
|
|
1066
|
+
}
|
|
602
1067
|
/**
|
|
603
1068
|
* Captures instance matrices at the framework's pre-render boundary and enables previous data on
|
|
604
1069
|
* every renderable in the graph. The previous snapshot is never the array the game writes next.
|
|
@@ -663,11 +1128,11 @@ interface IRenderChainVelocityResult {
|
|
|
663
1128
|
interface IRenderChainRenderer {
|
|
664
1129
|
readonly kind: RendererKind;
|
|
665
1130
|
readonly raw: unknown;
|
|
666
|
-
clearOutputNode?(): void;
|
|
1131
|
+
clearOutputNode?(expectedNode?: unknown): void;
|
|
667
1132
|
/** Internal renderer seam used to turn on core-owned previous-frame bookkeeping for active temporal stages. */
|
|
668
1133
|
setRenderChainVelocityEnabled?(enabled: boolean): void;
|
|
669
1134
|
/** Install a graph and identify the authored world pass that follows the rendered scene root. */
|
|
670
|
-
setOutputNode
|
|
1135
|
+
setOutputNode: RenderOutputSetter;
|
|
671
1136
|
}
|
|
672
1137
|
/** Quality values are algorithm parameters, not appearance values. Templates own the latter. */
|
|
673
1138
|
declare const RENDER_CHAIN_TIERS: {
|
|
@@ -695,6 +1160,12 @@ declare const RENDER_CHAIN_TIERS: {
|
|
|
695
1160
|
interface IRenderChainVelocityRequest {
|
|
696
1161
|
/** The scene pass that owns the shared velocity output. */
|
|
697
1162
|
pass?: IVelocityRenderPass;
|
|
1163
|
+
/**
|
|
1164
|
+
* Optional: how the chain builds the velocity output on `pass` and hands it through the composed
|
|
1165
|
+
* graph. Defaults to core's own {@link mrtVelocity}, so a web game never names it; a host whose
|
|
1166
|
+
* scene pass owns the output differently passes its own.
|
|
1167
|
+
*/
|
|
1168
|
+
provision?: IVelocityProvision;
|
|
698
1169
|
/** Treat the renderer's MRT velocity output as provisioned. */
|
|
699
1170
|
mrt?: boolean;
|
|
700
1171
|
/** Treat objects carrying `userData.useVelocity === true` as provisioned. */
|
|
@@ -719,16 +1190,32 @@ interface IRenderChainRequest {
|
|
|
719
1190
|
interface IRenderChainStageContext {
|
|
720
1191
|
readonly tier: RenderChainTier;
|
|
721
1192
|
readonly velocity: IRenderChainVelocityReport;
|
|
1193
|
+
/** Mutable target fractions supplied to generated stages for sub-rectangle sampling. */
|
|
1194
|
+
readonly resolutionSubrect?: IResolutionTextureView;
|
|
722
1195
|
/** TSL source handed to temporal stages when the request owns a scene pass. */
|
|
723
1196
|
readonly velocityNode?: Node;
|
|
724
1197
|
readonly quality: (typeof RENDER_CHAIN_TIERS)[RenderChainTier];
|
|
725
1198
|
}
|
|
726
1199
|
interface IRenderChainStage {
|
|
1200
|
+
readonly supportsResolutionSubrect?: boolean;
|
|
727
1201
|
readonly name: RenderChainStageId;
|
|
728
1202
|
/** Place an authored stage immediately before this built-in or supplied stage. */
|
|
729
1203
|
readonly before?: RenderChainStageId;
|
|
730
1204
|
/** Place an authored stage immediately after this built-in or supplied stage. */
|
|
731
1205
|
readonly after?: RenderChainStageId;
|
|
1206
|
+
/**
|
|
1207
|
+
* This stage reads display-referred colour, so the chain installs the graph with the renderer's
|
|
1208
|
+
* automatic output transform switched off and the stage applies that transform itself.
|
|
1209
|
+
*
|
|
1210
|
+
* Mechanism, not look. Some effects are defined against the sRGB picture — a `.cube` table, a
|
|
1211
|
+
* sharpening or edge filter — and bending scene-referred light into that domain costs precision
|
|
1212
|
+
* instead of buying anything: measured on an 8-bit table, a bijective log shaper costs 2–4
|
|
1213
|
+
* 8-bit steps per channel against under 1 for the transform this names (PRD-492).
|
|
1214
|
+
*
|
|
1215
|
+
* The stage therefore runs last, and may not declare an anchor: a stage placed after it would
|
|
1216
|
+
* receive display-referred colour it was not written for.
|
|
1217
|
+
*/
|
|
1218
|
+
readonly afterOutputTransform?: boolean;
|
|
732
1219
|
readonly build: (input: unknown, context: IRenderChainStageContext) => unknown;
|
|
733
1220
|
/** Stages below this tier are named as dropped instead of silently changing the graph. */
|
|
734
1221
|
readonly minimumTier?: RenderChainTier;
|
|
@@ -776,6 +1263,7 @@ interface IRenderChainBudgetWindow {
|
|
|
776
1263
|
};
|
|
777
1264
|
}
|
|
778
1265
|
interface IRenderChainOptions {
|
|
1266
|
+
readonly resolutionSubrect?: IResolutionSubrect;
|
|
779
1267
|
readonly renderer: IRenderChainRenderer;
|
|
780
1268
|
readonly input?: unknown;
|
|
781
1269
|
/** Explicit scene pass for output retargeting; avoids traversing a composed graph to find it. */
|
|
@@ -825,7 +1313,39 @@ declare class RenderChain {
|
|
|
825
1313
|
dispose(): void;
|
|
826
1314
|
}
|
|
827
1315
|
|
|
1316
|
+
/** The standard buffer fields this renderer seam verifies; the device handle stays opaque. */
|
|
1317
|
+
interface IRendererStorageBuffer {
|
|
1318
|
+
readonly size: number;
|
|
1319
|
+
readonly usage: number;
|
|
1320
|
+
readonly mapState: string;
|
|
1321
|
+
destroy(): void;
|
|
1322
|
+
}
|
|
1323
|
+
/** Exclusive allocation receipt. The solver borrows its handles and never destroys them. */
|
|
1324
|
+
interface IStorageBufferLease {
|
|
1325
|
+
readonly device: object;
|
|
1326
|
+
readonly buffer: IRendererStorageBuffer;
|
|
1327
|
+
readonly byteLength: number;
|
|
1328
|
+
readonly released: boolean;
|
|
1329
|
+
assertCurrent(): void;
|
|
1330
|
+
dispose(): void;
|
|
1331
|
+
}
|
|
1332
|
+
|
|
828
1333
|
type RendererKind = "webgpu" | "webgl2";
|
|
1334
|
+
/** Owns one output-pipeline installation, not the lifetime of its input graph dependencies. */
|
|
1335
|
+
interface IRenderOutputInstallation {
|
|
1336
|
+
isCurrent(): boolean;
|
|
1337
|
+
dispose(): void;
|
|
1338
|
+
}
|
|
1339
|
+
/**
|
|
1340
|
+
* Where the transform goes when a stage does the renderer's job for it. The chain passes
|
|
1341
|
+
* `false` only when a stage that read display-referred colour actually ran.
|
|
1342
|
+
*/
|
|
1343
|
+
interface IRenderOutputOptions {
|
|
1344
|
+
readonly outputColorTransform?: boolean;
|
|
1345
|
+
readonly resolutionSubrect?: IResolutionSubrect;
|
|
1346
|
+
}
|
|
1347
|
+
/** Union of callbacks preserves TypeScript's legacy void-callback return-value compatibility. */
|
|
1348
|
+
type RenderOutputSetter = ((node: unknown, worldPass?: unknown, options?: IRenderOutputOptions) => void) | ((node: unknown, worldPass?: unknown, options?: IRenderOutputOptions) => IRenderOutputInstallation);
|
|
829
1349
|
/**
|
|
830
1350
|
* Put transient meshes through the renderer's first-use shader path during loading.
|
|
831
1351
|
*
|
|
@@ -866,6 +1386,12 @@ interface IRendererLike {
|
|
|
866
1386
|
readonly compileCount?: number;
|
|
867
1387
|
/** The bounded, fail-closed pipeline observation for this renderer, when enabled. */
|
|
868
1388
|
readonly pipelineCensus?: () => IPipelineCensus;
|
|
1389
|
+
/** Marks the completion of the renderer's current scene warm-up attempt. */
|
|
1390
|
+
warmUpSettled?(): void;
|
|
1391
|
+
/** Marks a repeatable streamed warm-up boundary for the next first draw. */
|
|
1392
|
+
warmUpScopeSettled?(label: string, target?: Object3D): void;
|
|
1393
|
+
/** Performs one covered output-pipeline render without marking first present. */
|
|
1394
|
+
warmUpWorldPass?(scene: Object3D, camera: Camera, targetScene?: Object3D): void;
|
|
869
1395
|
/**
|
|
870
1396
|
* What alpha antialiasing did with the multisampled surface, and why, when it did nothing.
|
|
871
1397
|
*
|
|
@@ -878,7 +1404,77 @@ interface IRendererLike {
|
|
|
878
1404
|
* the `TN_ALPHA_ANTIALIASING` marker is printed either way, so nothing is only readable here.
|
|
879
1405
|
*/
|
|
880
1406
|
alphaAntialiasing?: () => IAlphaAntialiasingReport;
|
|
881
|
-
|
|
1407
|
+
/**
|
|
1408
|
+
* The `adapter.info` field value that identifies a CPU rasteriser — `swiftshader`, `llvmpipe`,
|
|
1409
|
+
* a `Microsoft Basic Render Driver` — when the adapter named one, else absent.
|
|
1410
|
+
*
|
|
1411
|
+
* Reading it needs `navigator.gpu`, so it is read here rather than in a game's render source.
|
|
1412
|
+
* It is a fact about the machine, not a look: which tier a game runs on a software adapter is
|
|
1413
|
+
* that game's own decision, and every tier name it might pick is already in its own
|
|
1414
|
+
* `src/render/quality.ts`. What this removes is the reason it could not make that decision
|
|
1415
|
+
* before its first expensive frame — a CPU rasteriser running a desktop render chain can lose
|
|
1416
|
+
* the device on the very first frame, which no adaptation after it survives.
|
|
1417
|
+
*
|
|
1418
|
+
* Absent means no software name was found, never that the adapter is hardware. The native host
|
|
1419
|
+
* exposes the same four `adapter.info` fields, so the same read works on every target.
|
|
1420
|
+
*/
|
|
1421
|
+
readonly softwareAdapter?: string;
|
|
1422
|
+
/**
|
|
1423
|
+
* The GPU family the adapter belongs to, the rule that named it and the four raw `adapter.info`
|
|
1424
|
+
* fields it was read from; absent when no adapter reported (a WebGL2 fallback).
|
|
1425
|
+
*
|
|
1426
|
+
* A fact about the machine, like `softwareAdapter`, and the better input for a start tier: it
|
|
1427
|
+
* tells a Mali-G52 from a Mali-G715 and an iGPU from a discrete card, where `mobile` and
|
|
1428
|
+
* `software` cannot. `unknown` means no rule matched; treat it as the behaviour before this
|
|
1429
|
+
* existed. Measurement still outranks it, and the class only picks where the first window starts.
|
|
1430
|
+
*/
|
|
1431
|
+
readonly gpuClass?: IGpuClassification;
|
|
1432
|
+
/** Advances the GPU sample once before a presented frame's simulation and render passes. */
|
|
1433
|
+
beginFrame?(): void;
|
|
1434
|
+
compute(node: unknown, span?: "depthPyramid"): void;
|
|
1435
|
+
/** Opt-in synchronous dispatch scope; consumes exact Three-owned query UID membership once resolved. */
|
|
1436
|
+
computeTiming?(operation: () => unknown, options?: {
|
|
1437
|
+
readonly maxCalls?: number;
|
|
1438
|
+
}): IComputeTimingReceipt;
|
|
1439
|
+
/**
|
|
1440
|
+
* Creates the GPU buffers these geometries draw from, through the backend's own attribute path,
|
|
1441
|
+
* and reports how many it created.
|
|
1442
|
+
*
|
|
1443
|
+
* `compileAsync` builds pipelines, not buffers: a streamed mesh's first draw is where its
|
|
1444
|
+
* attributes reach the device, and one chunk's first draw measured 230 ms of a frame for it. This
|
|
1445
|
+
* moves that to admission, one chunk at a time. WebGPU only — the WebGL fallback has no seam
|
|
1446
|
+
* this can call without inventing a GL enum — and absent or throwing answers 0, so the first
|
|
1447
|
+
* draw uploads exactly as it did before.
|
|
1448
|
+
*/
|
|
1449
|
+
uploadAttributes?(geometries: Iterable<BufferGeometry>): number;
|
|
1450
|
+
/** Exclusive Float32 vec4 storage on the existing WebGPU device; release its receipt on scene exit. */
|
|
1451
|
+
storageBuffer?(attribute: StorageBufferAttribute): IStorageBufferLease;
|
|
1452
|
+
/**
|
|
1453
|
+
* Copies one streamed subtree's textures to the device, through three's own texture path, and
|
|
1454
|
+
* reports how many it took.
|
|
1455
|
+
*
|
|
1456
|
+
* The same argument as `uploadAttributes`, one resource class over: `compileAsync` builds
|
|
1457
|
+
* pipelines, not pixels, so a streamed chunk's textures reach the device inside `_renderObjectDirect`
|
|
1458
|
+
* on the frame the chunk first draws. On a Machinefall map-walk with three's internals counted per
|
|
1459
|
+
* render, that was 87 ms of a 94 ms first draw in one frame, 79 ms of 131 ms in another, and 519 ms
|
|
1460
|
+
* in a third — 10 renders of 19,000 hold the whole 2,574 ms the run spends on first draws.
|
|
1461
|
+
* `Textures.updateTexture` returns early when the texture is already at its current version, so this
|
|
1462
|
+
* is a move rather than a second upload, and a material the world shares with what is already on
|
|
1463
|
+
* screen costs one call and no work. WebGPU only — the WebGL fallback has no seam here — and
|
|
1464
|
+
* absent or throwing answers 0, so the first draw uploads exactly as it did before.
|
|
1465
|
+
*/
|
|
1466
|
+
uploadTextures?(object: Object3D): number;
|
|
1467
|
+
/**
|
|
1468
|
+
* Prepares unique cold compressed textures before their first compile or draw. WebGPU uses
|
|
1469
|
+
* one upload lane, a measured 2 ms budget and at most 64 KiB per write; one final write may
|
|
1470
|
+
* overshoot the time budget. Await this gate before exposing the textures to rendering.
|
|
1471
|
+
* Original Texture/GPUTexture identities, formats and mip levels are retained. Cancellation
|
|
1472
|
+
* releases this caller's interest; another caller of the same texture may still complete.
|
|
1473
|
+
* Ordinary textures and the WebGL fallback retain their existing paths and report no work.
|
|
1474
|
+
* `onProgress` receives the completed unique compressed texture count after each preparation
|
|
1475
|
+
* promise resolves; queued textures and writes that have not settled receive no credit.
|
|
1476
|
+
*/
|
|
1477
|
+
prepareTextures?(textures: Iterable<Texture>, signal?: AbortSignal, onProgress?: (completed: number) => void): Promise<number>;
|
|
882
1478
|
/**
|
|
883
1479
|
* Copies one GPU storage attribute back to the CPU, asynchronously.
|
|
884
1480
|
*
|
|
@@ -886,14 +1482,29 @@ interface IRendererLike {
|
|
|
886
1482
|
* must cast through `.raw` to read its own simulation will either not read it or read it wrong.
|
|
887
1483
|
* The copy is asynchronous by nature — the caller gets the bytes some frames after the frame
|
|
888
1484
|
* that produced them, and `GPUReadback` is what turns that latency into a reported number
|
|
889
|
-
* instead of a silent one.
|
|
1485
|
+
* instead of a silent one. Pass a public ReadbackBuffer to own staging cleanup on rejected maps;
|
|
1486
|
+
* the returned bytes are copied before the caller disposes that target in finally.
|
|
1487
|
+
*/
|
|
1488
|
+
readback(attribute: unknown, target?: ReadbackBuffer): Promise<ArrayBuffer>;
|
|
1489
|
+
/**
|
|
1490
|
+
* The scene pass's stored depth attachment and sample count, from an authored pass or three's
|
|
1491
|
+
* internal framebuffer target. `undefined` when neither has rendered a depth to read.
|
|
1492
|
+
*
|
|
1493
|
+
* Optional because a backend that cannot render into a target of its own has no scene-pass depth to
|
|
1494
|
+
* hand over. A cull reads this every dispatch: on the frame it answers, the texture holds what the
|
|
1495
|
+
* previous frame's pass wrote, because this is asked before the frame draws.
|
|
890
1496
|
*/
|
|
891
|
-
|
|
1497
|
+
scenePassDepth?(): {
|
|
1498
|
+
readonly texture: DepthTexture;
|
|
1499
|
+
readonly width: number;
|
|
1500
|
+
readonly height: number;
|
|
1501
|
+
readonly samples?: number;
|
|
1502
|
+
} | undefined;
|
|
892
1503
|
render(scene: Object3D, camera: Camera): void;
|
|
893
1504
|
/** Draws after the world without clearing or passing through the world's output pipeline. */
|
|
894
1505
|
renderOverlay(scene: Object3D, camera: Camera): void;
|
|
895
|
-
/**
|
|
896
|
-
clearOutputNode?(): void;
|
|
1506
|
+
/** Legacy input-filtered clear; use an installation receipt for same-node replacement safety. */
|
|
1507
|
+
clearOutputNode?(expectedNode?: unknown): void;
|
|
897
1508
|
/** Creates the core-owned chain seam without making generated render source import the package. */
|
|
898
1509
|
createRenderChain?: (options: Omit<IRenderChainOptions, "renderer">) => RenderChain;
|
|
899
1510
|
/** Feeds automatic render-chain tiers the completed frame-budget window. */
|
|
@@ -905,7 +1516,8 @@ interface IRendererLike {
|
|
|
905
1516
|
/** Internal callback used by RenderChain; games should request velocity through the chain. */
|
|
906
1517
|
setRenderChainVelocityEnabled?: (enabled: boolean) => void;
|
|
907
1518
|
/** Installs a graph; pass the authored world pass when the graph contains auxiliary passes. */
|
|
908
|
-
setOutputNode
|
|
1519
|
+
setOutputNode: RenderOutputSetter;
|
|
1520
|
+
createResolutionSubrect?: () => IResolutionSubrect;
|
|
909
1521
|
setSize(width: number, height: number, updateStyle?: boolean): void;
|
|
910
1522
|
/**
|
|
911
1523
|
* The GPU time the last resolved frame actually cost, in milliseconds, or `undefined` when the
|
|
@@ -932,6 +1544,49 @@ interface IRendererLike {
|
|
|
932
1544
|
readonly frame: number;
|
|
933
1545
|
readonly ms: number;
|
|
934
1546
|
} | undefined;
|
|
1547
|
+
/**
|
|
1548
|
+
* Observes complete allocated render-query groups without changing ordinary sampling.
|
|
1549
|
+
* Frame IDs are Three query IDs, including any overlay draws; callers map world callbacks.
|
|
1550
|
+
* Capacities bound undrained, pending and queued membership. maxQueries counts timestamp
|
|
1551
|
+
* slots (two per pass). A failed receipt is sticky and must be disposed before replacement.
|
|
1552
|
+
* Requires timestamp-capable WebGPU and its existing asynchronous resolver.
|
|
1553
|
+
*/
|
|
1554
|
+
observeGpuFrames?(options: IGpuFrameObservationOptions): IGpuFrameObservation;
|
|
1555
|
+
/**
|
|
1556
|
+
* GPU milliseconds of the last resolved compute frame, when the adapter reports one.
|
|
1557
|
+
*
|
|
1558
|
+
* The compute pool is a separate series from the render pool and `resolveGpuFrame` resolves it,
|
|
1559
|
+
* so a GPU simulation's cost is measurable instead of being charged to whatever render frame
|
|
1560
|
+
* happened to overlap. `undefined` for a WebGL2 fallback, an adapter without timestamps, or a
|
|
1561
|
+
* frame that ran no compute.
|
|
1562
|
+
*/
|
|
1563
|
+
gpuComputeMs?(): number | undefined;
|
|
1564
|
+
/** Consume one fresh timestamped pyramid build, including its depth resolve; absent until resolved. */
|
|
1565
|
+
gpuPyramidMs?(): number | undefined;
|
|
1566
|
+
/**
|
|
1567
|
+
* The main render pass's GPU milliseconds, smoothed over fresh resolved samples, or `undefined`
|
|
1568
|
+
* while no reading is fresh.
|
|
1569
|
+
*
|
|
1570
|
+
* `gpuFrameMs` is the whole render pool, main plus every shadow, reflection, post and HUD pass;
|
|
1571
|
+
* the adaptive LOD control loop needs the main-pass share alone. `game.ts` splits the resolved
|
|
1572
|
+
* frame through the pass recorder and feeds the sample here with {@link noteGpuMainMs}. A
|
|
1573
|
+
* repeated frame id is a resolve still in flight and not a new reading, and with no fresh sample
|
|
1574
|
+
* for too long the value reads absent, so a caller never adapts on a stale number.
|
|
1575
|
+
*/
|
|
1576
|
+
gpuMainMs?(): number | undefined;
|
|
1577
|
+
/**
|
|
1578
|
+
* Records one resolved frame's main-pass GPU milliseconds into {@link gpuMainMs}. Called once a
|
|
1579
|
+
* frame by `game.ts`; `ms` is `undefined` when the frame attributed no main-pass reading.
|
|
1580
|
+
*/
|
|
1581
|
+
noteGpuMainMs?(ms: number | undefined, frame?: number): void;
|
|
1582
|
+
/**
|
|
1583
|
+
* The frame rate the game resolved as its target (`resolveTargetFps`), or `undefined` before one
|
|
1584
|
+
* is known or when it is uncapped. Budgets that are a share of a frame read it, so a frame that ran
|
|
1585
|
+
* faster than the target does not shrink what the next one may spend.
|
|
1586
|
+
*/
|
|
1587
|
+
targetFps?(): number | undefined;
|
|
1588
|
+
/** Records the resolved target; called by `game.ts` when it resolves or retargets. */
|
|
1589
|
+
noteTargetFps?(fps: number): void;
|
|
935
1590
|
/** Starts a resolve of the GPU timestamps for the frames drawn since the last call. */
|
|
936
1591
|
resolveGpuFrame(): void;
|
|
937
1592
|
/**
|
|
@@ -1001,4 +1656,4 @@ interface IRendererOptions {
|
|
|
1001
1656
|
}>) => unknown;
|
|
1002
1657
|
}
|
|
1003
1658
|
|
|
1004
|
-
export {
|
|
1659
|
+
export { RENDER_CHAIN_TIERS as $, type IRenderChainDroppedStage as A, type IRenderChainOptions as B, type IRenderChainRenderer as C, DEFAULT_PIPELINE_CENSUS_LIMIT as D, type IRenderChainRequest as E, type FramePassKind as F, type IRenderChainStage as G, type IRenderChainStageContext as H, type IRendererLike as I, type IRenderChainVelocityMeasurement as J, type IRenderChainVelocityReport as K, type IRenderChainVelocityRequest as L, type IRenderChainVelocityResult as M, type ITargetFps as N, type IVelocityRenderPass as O, MAX_TARGET_FPS as P, type MainDrawSource as Q, PIPELINE_CENSUS_CAPABILITY as R, PIPELINE_CENSUS_VERSION as S, PipelineCensus as T, type PipelineCensusMode as U, type PipelineCensusStatus as V, type PlatformFormFactor as W, type PlatformOS as X, type PlatformRuntime as Y, RENDER_CHAIN_MARKER as Z, RENDER_CHAIN_STAGE_ORDER as _, type IFrameBudgetWindow as a, RenderChain as a0, type RenderChainSource as a1, type RenderChainStageId as a2, type RenderChainStageName as a3, type RenderChainTier as a4, type RenderChainTierRequest as a5, type RenderChainVelocitySource as a6, type TargetFpsSource as a7, VELOCITY_OUTPUT_NAME as a8, VELOCITY_PREVIOUS_BONE_MATRICES as a9, VELOCITY_PREVIOUS_INSTANCE_MATRICES as aa, VELOCITY_PREVIOUS_WORLD_MATRIX as ab, VelocityTracker as ac, counterDeviceOf as ad, createPipelineCensus as ae, ensureVelocityOutput as af, getPlatform as ag, isMobile as ah, isNative as ai, isTouchscreenAvailable as aj, isWeb as ak, prewarm as al, readRenderChainObservation as am, readRenderChainReport as an, readVelocityPreviousBoneMatrices as ao, readVelocityPreviousMatrices as ap, readVelocityPreviousWorldMatrix as aq, resolveTargetFps as ar, snapRefreshRate as as, velocityTexture as at, withVelocityContext as au, type IFrameBudgetSimulation as b, type IRenderPassSample as c, type IFramePhaseSample as d, type IPipelineCensus as e, type IRendererOptions as f, type IFrameBudgetOptions as g, DEFAULT_TARGET_FPS as h, FRAME_BUDGET_MARKER as i, FRAME_BUDGET_PHASES as j, FRAME_HITCH_MARKER as k, FrameBudget as l, type FrameBudgetPhase as m, FrameCounters as n, type ICounterDevice as o, type IFrameBudgetPassSummary as p, type IFrameBudgetSummary as q, type IFrameCounters as r, type IPipelineCensusCounts as s, type IPipelineCensusEvent as t, type IPipelineCensusOptions as u, type IPipelineProvenance as v, type IPipelineShaderObservation as w, type IPlatformInfo as x, type IRenderChainApplied as y, type IRenderChainBudgetWindow as z };
|