@threenative/core 0.3.4 → 0.3.6
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 +1505 -79
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-CljaDv4D.d.ts → game-Jz4Fdoeb.d.ts} +114 -11
- package/dist/hot.d.ts +4 -4
- package/dist/index.d.ts +712 -118
- package/dist/index.js +12437 -4955
- package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
- package/dist/playtest.d.ts +6 -10
- package/dist/playtest.js +57 -24
- 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-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +766 -73
- package/dist/world.js +9307 -3543
- package/gpl/recipes/export_world.py +18 -1
- package/mcp/blender-server.mjs +7 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +2 -2
- 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 +6594 -700
- package/scripts/apply-three-patch.mjs +62 -4
- 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 +2408 -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 +574 -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 +850 -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
|
@@ -0,0 +1,501 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Per-pass draw and triangle attribution, on by default, for every platform.
|
|
3
|
+
*
|
|
4
|
+
* The frame budget already owned the milliseconds; this owns the submissions. Three's
|
|
5
|
+
* `renderer.info.reset()` runs once per frame before the world render, and a nested shadow or
|
|
6
|
+
* reflection `renderer.render(...)` shares that same `info`, so `info.render` reports main plus
|
|
7
|
+
* every nested pass combined. The aggregate cannot tell a 316-draw shadow lane from a 1,418-draw
|
|
8
|
+
* colour pass, and every optimisation attempt had to hand-roll the split. This is the split: each
|
|
9
|
+
* `render()` is one entry on a stack, and its own submissions are the counter delta across its
|
|
10
|
+
* call minus the deltas of the nested calls it made, so the innermost active render call owns
|
|
11
|
+
* exactly what it submitted.
|
|
12
|
+
*
|
|
13
|
+
* Three names its own shadow pass by temporarily renaming the scene to `Shadow Map [ ... ]`
|
|
14
|
+
* (`renderShadow`), and a reflection pass names its scene with `Reflector` in it. Those are
|
|
15
|
+
* borrowed, not invented: the classifier reads three's vocabulary and falls back to `nested`.
|
|
16
|
+
*
|
|
17
|
+
* Measurement, not policy: installing this alters no draw. `install` answers `undefined` on a
|
|
18
|
+
* renderer whose `info.render` cannot be read, and a consumer must then report the pass split as
|
|
19
|
+
* absent rather than zero.
|
|
20
|
+
*
|
|
21
|
+
* The main pass's own draws are also split by where their mesh came from, counted at the one place
|
|
22
|
+
* a draw is counted — `info.update`, which every backend calls per submitted draw with the object
|
|
23
|
+
* that owns it — so the sources sum to `draws` by construction instead of by an estimate beside it.
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
/** The named kinds of a render pass. Closed on purpose: a consumer bounds a known kind. */
|
|
27
|
+
export const FRAME_PASS_KINDS = ["main", "shadow", "reflection", "nested"] as const;
|
|
28
|
+
|
|
29
|
+
export type FramePassKind = (typeof FRAME_PASS_KINDS)[number];
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Where a main-pass draw's mesh came from. Closed, and `other` is the default.
|
|
33
|
+
*
|
|
34
|
+
* Each entry is a system that owns its meshes and writes the origin on them, so the split reads as
|
|
35
|
+
* an answer about systems rather than about geometry: `gpuScene` and `bundles` are `WorldCells`' two
|
|
36
|
+
* ways of drawing one main batch (a GPU-dressed key, and the same mesh replayed from the world's
|
|
37
|
+
* bundle), `terrain` is every mesh `world-tiles.ts` creates, `proxies` is the shadow halves and the
|
|
38
|
+
* whole-map impostor aggregates, `chunks` is a hand-placed chunk's own draws, `instanced` is a main
|
|
39
|
+
* batch the GPU scene never dressed, and `sky` is a daylight rig's sky box. What is left in `other`
|
|
40
|
+
* is a mesh no world system claimed — a character, a prop, a water surface the game loaded — which is
|
|
41
|
+
* the bucket that has to be small enough to be worth naming one draw at a time.
|
|
42
|
+
*/
|
|
43
|
+
export const MAIN_DRAW_SOURCES = [
|
|
44
|
+
"gpuScene",
|
|
45
|
+
"bundles",
|
|
46
|
+
"terrain",
|
|
47
|
+
"proxies",
|
|
48
|
+
"chunks",
|
|
49
|
+
"instanced",
|
|
50
|
+
"sky",
|
|
51
|
+
"other",
|
|
52
|
+
] as const;
|
|
53
|
+
|
|
54
|
+
export type MainDrawSource = (typeof MAIN_DRAW_SOURCES)[number];
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* One render call's own submissions, attributed to its innermost active render call.
|
|
58
|
+
*
|
|
59
|
+
* `drawsBySource` is `main`'s own draws by origin, in the frame's counts rather than in percentiles:
|
|
60
|
+
* it sums to `draws` for the frame, which is the claim the split exists to answer. Absent when the
|
|
61
|
+
* renderer named no object for one of those draws, because a split that guessed where a draw came
|
|
62
|
+
* from would read as a measurement.
|
|
63
|
+
*/
|
|
64
|
+
export interface IRenderPassSample {
|
|
65
|
+
readonly draws: number;
|
|
66
|
+
readonly drawsBySource?: Readonly<Partial<Record<MainDrawSource, number>>>;
|
|
67
|
+
readonly kind: FramePassKind;
|
|
68
|
+
readonly triangles: number;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Whether a tag names a source this file counts. Anything else is `other`. */
|
|
72
|
+
function isMainDrawSource(tag: unknown): tag is MainDrawSource {
|
|
73
|
+
return (MAIN_DRAW_SOURCES as readonly unknown[]).includes(tag);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* The source a drawn object belongs to, read from the two tags its creator set on it.
|
|
78
|
+
*
|
|
79
|
+
* `tnBundled` is the marker `WorldCells` already keeps, and it wins: a bundled mesh is a mesh the
|
|
80
|
+
* world drew through a recorded `BundleGroup` rather than one it submitted per object, so counting
|
|
81
|
+
* it as a GPU-scene key as well would name the same draw twice.
|
|
82
|
+
*/
|
|
83
|
+
function drawSourceOf(object: unknown): MainDrawSource | undefined {
|
|
84
|
+
const userData =
|
|
85
|
+
typeof object === "object" && object !== null
|
|
86
|
+
? (object as { readonly userData?: Record<string, unknown> }).userData
|
|
87
|
+
: undefined;
|
|
88
|
+
if (typeof userData !== "object" || userData === null) return undefined;
|
|
89
|
+
if (userData.tnBundled === true) return "bundles";
|
|
90
|
+
const tagged = userData.tnDrawSource;
|
|
91
|
+
return isMainDrawSource(tagged) ? tagged : "other";
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
interface IRenderCounters {
|
|
95
|
+
readonly drawCalls?: number;
|
|
96
|
+
readonly calls?: number;
|
|
97
|
+
readonly triangles?: number;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Three's own per-frame counters, the surface this file reads and wraps.
|
|
102
|
+
*
|
|
103
|
+
* `update` is three's per-draw counter, not one of the aggregates: WebGPU's `WebGPUInfo` and the
|
|
104
|
+
* WebGL2 fallback inside it both call it once per submitted draw with the object that owns it, and
|
|
105
|
+
* a standalone `WebGLRenderer` calls it with a vertex count instead — which is why a draw this
|
|
106
|
+
* cannot read a `userData` off is left unattributed rather than guessed at.
|
|
107
|
+
*/
|
|
108
|
+
interface IInfoCounters {
|
|
109
|
+
readonly render?: IRenderCounters | undefined;
|
|
110
|
+
update?(object: unknown, count: number, instanceCount: number): void;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* The slice of three's timestamp query pool this reads.
|
|
115
|
+
*
|
|
116
|
+
* Three keys one pool per query type (`render`, `compute`) at
|
|
117
|
+
* `renderer.backend.timestampQueryPool`, and each pool exposes the two maps it fills in itself:
|
|
118
|
+
* `queryOffsets` is the uid of every allocated pass (appended synchronously as the pass begins,
|
|
119
|
+
* cleared when a resolve starts) and `timestamps` is every uid's resolved duration in
|
|
120
|
+
* milliseconds, written when the asynchronous resolve lands. Both are three's own public fields,
|
|
121
|
+
* not a borrowed internal, and reading them is what turns the one summed `info.render.timestamp`
|
|
122
|
+
* into a per-pass number.
|
|
123
|
+
*/
|
|
124
|
+
export interface ITimestampQueryPool {
|
|
125
|
+
readonly queryOffsets?: Map<string, number> | undefined;
|
|
126
|
+
readonly timestamps?: Map<string, number> | undefined;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* The slice of a renderer this reads: the raw three renderer, not `IRendererLike`. It is
|
|
131
|
+
* deliberately structural so the unit test can stand in a fake that nests exactly as three does.
|
|
132
|
+
*/
|
|
133
|
+
export interface IRenderPassTarget {
|
|
134
|
+
readonly info?: IInfoCounters | undefined;
|
|
135
|
+
/**
|
|
136
|
+
* Three's backend, for per-pass GPU time. Optional: a WebGL2 fallback and a test double may
|
|
137
|
+
* carry no timestamp pool, and every GPU read is then absent rather than zero.
|
|
138
|
+
*/
|
|
139
|
+
readonly backend?:
|
|
140
|
+
| { readonly timestampQueryPool?: Record<string, ITimestampQueryPool | null> }
|
|
141
|
+
| undefined;
|
|
142
|
+
render(scene: unknown, camera: unknown): void;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/** One allocated timestamp query, before its duration resolves: the pass kind and three's uid. */
|
|
146
|
+
interface IGpuUidEntry {
|
|
147
|
+
readonly kind: FramePassKind;
|
|
148
|
+
readonly uid: string;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* One resolved frame's GPU milliseconds: the frame it belongs to, its own passes, and every pass it
|
|
153
|
+
* drew. `total` is the frame's cost — three's `framesDuration` for that frame, read back from the
|
|
154
|
+
* per-pass map rather than from the single number its resolve returns.
|
|
155
|
+
*
|
|
156
|
+
* A reading exists only when **every** pass the frame recorded has a resolved timestamp. A frame
|
|
157
|
+
* with any pass still in flight understates the frame's cost if its resolved parts were summed and
|
|
158
|
+
* forwarded as the whole, so it stays absent until the read is complete. Frames are delivered in
|
|
159
|
+
* order and an unresolved one is skipped, never waited on: once a newer frame is delivered the
|
|
160
|
+
* older unresolved frame is intentionally omitted — a missing reading, never a partial zero.
|
|
161
|
+
*/
|
|
162
|
+
export interface IGpuFrameReading {
|
|
163
|
+
readonly frame: number;
|
|
164
|
+
/** Milliseconds the main pass cost. `0` when the frame drew none; whole whenever the frame is. */
|
|
165
|
+
readonly main: number;
|
|
166
|
+
/**
|
|
167
|
+
* Every shadow pass's milliseconds: `0` when the frame drew none. A resolved `0` is a real
|
|
168
|
+
* render that cost nothing, so {@link shadowPasses} — not this value — says whether one was made.
|
|
169
|
+
*/
|
|
170
|
+
readonly shadow: number;
|
|
171
|
+
/**
|
|
172
|
+
* How many shadow passes the frame recorded. `0` means it drew no shadow; `> 0` means it rendered
|
|
173
|
+
* one, however small the cost. This is the producer's own record, so a consumer never has to guess
|
|
174
|
+
* "rendered" from a value that a genuine render can leave at zero.
|
|
175
|
+
*/
|
|
176
|
+
readonly shadowPasses: number;
|
|
177
|
+
/** Every resolved pass of the frame — main, shadow and everything else. Whole, never partial. */
|
|
178
|
+
readonly total: number;
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
interface IPassFrame {
|
|
182
|
+
readonly entryDraws: number;
|
|
183
|
+
readonly entryTriangles: number;
|
|
184
|
+
readonly kind: FramePassKind;
|
|
185
|
+
childDraws: number;
|
|
186
|
+
childTriangles: number;
|
|
187
|
+
/** Timestamp uids the nested calls this pass made allocated, in allocation order. */
|
|
188
|
+
childUids?: string[];
|
|
189
|
+
/** This pass's own draws per origin, held only for a main pass and dropped the moment one is unclassifiable. */
|
|
190
|
+
drawsBySource?: Partial<Record<MainDrawSource, number>>;
|
|
191
|
+
/** A draw named no object to read, so {@link drawsBySource} would be a partial answer. */
|
|
192
|
+
unclassifiable?: boolean;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
function readCounters(target: IRenderPassTarget): { draws: number; triangles: number } | undefined {
|
|
196
|
+
const render = target.info?.render;
|
|
197
|
+
if (render === undefined) return undefined;
|
|
198
|
+
const draws = render.drawCalls ?? render.calls;
|
|
199
|
+
const triangles = render.triangles;
|
|
200
|
+
if (typeof draws !== "number" || !Number.isFinite(draws) || draws < 0) return undefined;
|
|
201
|
+
if (typeof triangles !== "number" || !Number.isFinite(triangles) || triangles < 0)
|
|
202
|
+
return undefined;
|
|
203
|
+
return { draws, triangles };
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
const installed = new WeakSet<object>();
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Resolved frames kept for GPU attribution. A resolve lags the frame it measures by a few frames,
|
|
210
|
+
* so the uid list for a frame must outlive the frame that produced it; 64 frames is far more than
|
|
211
|
+
* that lag and bounds the map on a game that never resolves.
|
|
212
|
+
*/
|
|
213
|
+
const GPU_UID_FRAME_LIMIT = 64;
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* Names a render call by what three already calls it: the outermost call is the main camera, and a
|
|
217
|
+
* nested call carries the scene name three or the reflector gave it.
|
|
218
|
+
*/
|
|
219
|
+
function passKind(scene: unknown, depth: number): FramePassKind {
|
|
220
|
+
if (depth === 0) return "main";
|
|
221
|
+
const name =
|
|
222
|
+
typeof scene === "object" &&
|
|
223
|
+
scene !== null &&
|
|
224
|
+
typeof (scene as { name?: unknown }).name === "string"
|
|
225
|
+
? (scene as { name: string }).name
|
|
226
|
+
: "";
|
|
227
|
+
if (name.startsWith("Shadow Map")) return "shadow";
|
|
228
|
+
if (/reflect/iu.test(name)) return "reflection";
|
|
229
|
+
return "nested";
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* Records one presented frame's passes. The owner calls `beginFrame` before the world render and
|
|
234
|
+
* `passes()` after it; a nested render inside the world render is attributed without the owner
|
|
235
|
+
* knowing it happened.
|
|
236
|
+
*/
|
|
237
|
+
/** The last resolved shadow-pass GPU milliseconds per instrumented renderer; see {@link shadowRedrawGpuMs}. */
|
|
238
|
+
const lastShadowGpuMs = new WeakMap<object, number>();
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* What the last resolved frame that drew a shadow spent on its shadow passes, on this renderer, or
|
|
242
|
+
* `undefined` before one resolved (or with no recorder installed). A shadow node reads it to price
|
|
243
|
+
* a redraw in GPU time: its own `performance.now()` around the draw is only the CPU encode.
|
|
244
|
+
*/
|
|
245
|
+
export function shadowRedrawGpuMs(renderer: unknown): number | undefined {
|
|
246
|
+
return typeof renderer === "object" && renderer !== null
|
|
247
|
+
? lastShadowGpuMs.get(renderer)
|
|
248
|
+
: undefined;
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/** Records a resolved shadow-pass reading for {@link shadowRedrawGpuMs}; the recorder's own feed. */
|
|
252
|
+
export function noteShadowRedrawGpuMs(renderer: object, ms: number): void {
|
|
253
|
+
lastShadowGpuMs.set(renderer, ms);
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
export class RenderPassBudget {
|
|
257
|
+
readonly #target: IRenderPassTarget;
|
|
258
|
+
readonly #original: (scene: unknown, camera: unknown) => void;
|
|
259
|
+
readonly #frame: IRenderPassSample[] = [];
|
|
260
|
+
readonly #stack: IPassFrame[] = [];
|
|
261
|
+
/** Timestamp uids each render call allocated, keyed by the Three.js frame they belong to. */
|
|
262
|
+
readonly #gpuUids = new Map<number, IGpuUidEntry[]>();
|
|
263
|
+
/** The last frame `nextGpuFrame` handed out; every earlier frame has been reported. */
|
|
264
|
+
#deliveredGpuFrame = -1;
|
|
265
|
+
|
|
266
|
+
private constructor(target: IRenderPassTarget) {
|
|
267
|
+
this.#target = target;
|
|
268
|
+
this.#original = target.render;
|
|
269
|
+
const instrumented = (scene: unknown, camera: unknown): void => {
|
|
270
|
+
const counters = readCounters(target);
|
|
271
|
+
if (counters === undefined) {
|
|
272
|
+
this.#original.call(target, scene, camera);
|
|
273
|
+
return;
|
|
274
|
+
}
|
|
275
|
+
const offsets = target.backend?.timestampQueryPool?.render?.queryOffsets;
|
|
276
|
+
const allocatedBefore = offsets?.size ?? 0;
|
|
277
|
+
const depth = this.#stack.length;
|
|
278
|
+
const frame: IPassFrame = {
|
|
279
|
+
childDraws: 0,
|
|
280
|
+
childTriangles: 0,
|
|
281
|
+
entryDraws: counters.draws,
|
|
282
|
+
entryTriangles: counters.triangles,
|
|
283
|
+
kind: passKind(scene, depth),
|
|
284
|
+
};
|
|
285
|
+
this.#stack.push(frame);
|
|
286
|
+
try {
|
|
287
|
+
this.#original.call(target, scene, camera);
|
|
288
|
+
} finally {
|
|
289
|
+
this.#stack.pop();
|
|
290
|
+
const after = readCounters(target);
|
|
291
|
+
if (after !== undefined) {
|
|
292
|
+
const totalDraws = after.draws - frame.entryDraws;
|
|
293
|
+
const totalTriangles = after.triangles - frame.entryTriangles;
|
|
294
|
+
const parent = this.#stack[this.#stack.length - 1];
|
|
295
|
+
if (parent !== undefined) {
|
|
296
|
+
parent.childDraws += totalDraws;
|
|
297
|
+
parent.childTriangles += totalTriangles;
|
|
298
|
+
}
|
|
299
|
+
const drawsBySource = frame.unclassifiable === true ? undefined : frame.drawsBySource;
|
|
300
|
+
this.#frame.push({
|
|
301
|
+
draws: Math.max(0, totalDraws - frame.childDraws),
|
|
302
|
+
...(drawsBySource === undefined ? {} : { drawsBySource }),
|
|
303
|
+
kind: frame.kind,
|
|
304
|
+
triangles: Math.max(0, totalTriangles - frame.childTriangles),
|
|
305
|
+
});
|
|
306
|
+
}
|
|
307
|
+
this.#attributeGpu(frame, offsets, allocatedBefore);
|
|
308
|
+
}
|
|
309
|
+
};
|
|
310
|
+
target.render = instrumented;
|
|
311
|
+
this.#instrumentDraws(target.info);
|
|
312
|
+
installed.add(target);
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
/**
|
|
316
|
+
* Attributes each counted draw to the origin of the object behind it.
|
|
317
|
+
*
|
|
318
|
+
* Only a draw the main pass itself submitted is counted, because a nested render's draws are
|
|
319
|
+
* subtracted out of `main`: counting them here too would put shadow work in the main pass's split
|
|
320
|
+
* and break the sum the split exists to reconcile. The original `update` still runs, so
|
|
321
|
+
* `info.render.drawCalls` — the number everything else is read against — is untouched.
|
|
322
|
+
*/
|
|
323
|
+
#instrumentDraws(info: IInfoCounters | undefined): void {
|
|
324
|
+
const update = info?.update;
|
|
325
|
+
if (info === undefined || typeof update !== "function") return;
|
|
326
|
+
info.update = (object: unknown, count: number, instanceCount: number): void => {
|
|
327
|
+
const frame = this.#stack[this.#stack.length - 1];
|
|
328
|
+
if (frame?.kind === "main" && frame.unclassifiable !== true) {
|
|
329
|
+
const source = drawSourceOf(object);
|
|
330
|
+
if (source === undefined) frame.unclassifiable = true;
|
|
331
|
+
else {
|
|
332
|
+
frame.drawsBySource ??= {};
|
|
333
|
+
const drawsBySource = frame.drawsBySource;
|
|
334
|
+
drawsBySource[source] = (drawsBySource[source] ?? 0) + 1;
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
update.call(info, object, count, instanceCount);
|
|
338
|
+
};
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
/**
|
|
342
|
+
* Instruments `target`'s `render` in place and answers the recorder, or `undefined` when the
|
|
343
|
+
* renderer cannot report its own counters. Refuses a double install: one frame must not be
|
|
344
|
+
* counted twice.
|
|
345
|
+
*/
|
|
346
|
+
static install(target: IRenderPassTarget): RenderPassBudget | undefined {
|
|
347
|
+
if (installed.has(target)) return undefined;
|
|
348
|
+
if (readCounters(target) === undefined) return undefined;
|
|
349
|
+
return new RenderPassBudget(target);
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/**
|
|
353
|
+
* The kind of the innermost render call currently running, or undefined outside one.
|
|
354
|
+
*
|
|
355
|
+
* A per-object diagnostic needs the same attribution this class already does: a mesh submitted
|
|
356
|
+
* inside a shadow render is shadow work, and charging it to the main pass is how a shadow map
|
|
357
|
+
* disappears from a cost report.
|
|
358
|
+
*/
|
|
359
|
+
activeKind(): FramePassKind | undefined {
|
|
360
|
+
return this.#stack[this.#stack.length - 1]?.kind;
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
/** Clears the previous frame's passes. Call before the frame's first world render. */
|
|
364
|
+
beginFrame(): void {
|
|
365
|
+
this.#frame.length = 0;
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
/**
|
|
369
|
+
* The passes just recorded, children before the main call. The array is reused, so a consumer
|
|
370
|
+
* reads it before the next `beginFrame`.
|
|
371
|
+
*/
|
|
372
|
+
passes(): readonly IRenderPassSample[] {
|
|
373
|
+
return this.#frame;
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
/**
|
|
377
|
+
* The oldest resolved frame that has not been handed out yet, and where its GPU time went.
|
|
378
|
+
*
|
|
379
|
+
* Three answers a resolve with **one** number: the summed duration of the last frame in the
|
|
380
|
+
* batch (`three.webgpu.js:83746`). Every other frame that batch measured is written to the pool's
|
|
381
|
+
* own `timestamps` map, one entry per pass, keyed by the frame its uid names, and read by nobody.
|
|
382
|
+
* A resolve that caught up on k sampled frames therefore reported one of them, and the k-1 others
|
|
383
|
+
* were gone for good, because the pool is emptied before the resolve is submitted and the next one
|
|
384
|
+
* starts from nothing.
|
|
385
|
+
*
|
|
386
|
+
* That is what made the frame budget's sample count a function of frame *rate*: the engine asked
|
|
387
|
+
* for a resolve on the same 1-in-8 stride it samples on, three skips a resolve while one is still
|
|
388
|
+
* in flight, and the stride is a frame count where the round trip is not — so the faster the game
|
|
389
|
+
* presented, the fewer samples a window carried (28 in a 300-frame window on the 2026-10-03
|
|
390
|
+
* Machinefall probe, 1-2 in its ~200 fps windows, against the ~37 the sampler asked for).
|
|
391
|
+
*
|
|
392
|
+
* The uid list per frame is already kept here, so the batch is walked instead of collapsed: one
|
|
393
|
+
* sample per presented frame, one frame per sample, which is the shape the budget's series wants.
|
|
394
|
+
* Frames are delivered in uid order and an unresolved one is skipped rather than waited on, so no
|
|
395
|
+
* one frame ever stalls the frames behind it. An unresolved frame is retried only while it is the
|
|
396
|
+
* oldest undelivered one: the moment a newer complete frame is delivered, the cursor moves past
|
|
397
|
+
* the gap and the older unresolved frame is intentionally omitted — a missing reading, never a
|
|
398
|
+
* zeroed partial. Only the bounded uid ring retires a frame that never resolves at all.
|
|
399
|
+
*
|
|
400
|
+
* A kind with no pass in the frame is zero, not absent: a frame that drew a main pass and no
|
|
401
|
+
* shadow genuinely spent 0 ms on shadow. A frame is absent, though, until **every** pass it
|
|
402
|
+
* recorded has resolved: its parts are only a whole frame when the whole frame came back, and a
|
|
403
|
+
* partial `total` forwarded as the frame's cost is what the phase comparison must not read.
|
|
404
|
+
* The caller subtracts the known kinds from `total` to leave `other` (post chain, reflection,
|
|
405
|
+
* HUD). Passes are summed per kind, so a shadow cascade's several passes are one number, and main
|
|
406
|
+
* never absorbs the nested shadow's.
|
|
407
|
+
*/
|
|
408
|
+
nextGpuFrame(): IGpuFrameReading | undefined {
|
|
409
|
+
for (const frame of this.#gpuUids.keys()) {
|
|
410
|
+
if (frame <= this.#deliveredGpuFrame) continue;
|
|
411
|
+
const sum = this.#gpuSum(frame);
|
|
412
|
+
if (sum === undefined) continue;
|
|
413
|
+
this.#deliveredGpuFrame = frame;
|
|
414
|
+
if (sum.shadowPasses > 0) noteShadowRedrawGpuMs(this.#target, sum.shadow);
|
|
415
|
+
return {
|
|
416
|
+
frame,
|
|
417
|
+
main: sum.main,
|
|
418
|
+
shadow: sum.shadow,
|
|
419
|
+
shadowPasses: sum.shadowPasses,
|
|
420
|
+
total: sum.total,
|
|
421
|
+
};
|
|
422
|
+
}
|
|
423
|
+
return undefined;
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
/**
|
|
427
|
+
* One frame's resolved GPU milliseconds from the pool's per-pass map, or `undefined` until every
|
|
428
|
+
* pass it recorded has come back. `total` is every resolved pass of the frame — main, shadow and
|
|
429
|
+
* everything else — so the frame's own cost does not have to be inferred from three's one number
|
|
430
|
+
* for the batch, and it is only ever returned whole.
|
|
431
|
+
*/
|
|
432
|
+
#gpuSum(
|
|
433
|
+
frame: number,
|
|
434
|
+
): { main: number; shadow: number; shadowPasses: number; total: number } | undefined {
|
|
435
|
+
const entries = this.#gpuUids.get(frame);
|
|
436
|
+
const timestamps = this.#target.backend?.timestampQueryPool?.render?.timestamps;
|
|
437
|
+
if (timestamps === undefined || entries === undefined || entries.length === 0) return undefined;
|
|
438
|
+
let main = 0;
|
|
439
|
+
let shadow = 0;
|
|
440
|
+
let shadowPasses = 0;
|
|
441
|
+
let total = 0;
|
|
442
|
+
let resolved = 0;
|
|
443
|
+
for (const { kind, uid } of entries) {
|
|
444
|
+
if (kind === "shadow") shadowPasses += 1;
|
|
445
|
+
const ms = timestamps.get(uid);
|
|
446
|
+
if (ms === undefined || !Number.isFinite(ms) || ms < 0) continue;
|
|
447
|
+
resolved += 1;
|
|
448
|
+
total += ms;
|
|
449
|
+
if (kind === "main") main += ms;
|
|
450
|
+
else if (kind === "shadow") shadow += ms;
|
|
451
|
+
}
|
|
452
|
+
// A partial sum is not the frame's cost: subtracting the known kinds from a partial `total`
|
|
453
|
+
// leaves an `other` no one measured. The frame stays absent until the whole read is in.
|
|
454
|
+
if (resolved !== entries.length) return undefined;
|
|
455
|
+
return { main, shadow, shadowPasses, total };
|
|
456
|
+
}
|
|
457
|
+
|
|
458
|
+
/**
|
|
459
|
+
* Attributes the uids allocated during one render call to that call, not its parent, by the same
|
|
460
|
+
* child-subtraction the draws get: a nested render's uids are claimed by the nested frame before
|
|
461
|
+
* the parent computes its own, so `main` does not absorb a shadow's pass.
|
|
462
|
+
*/
|
|
463
|
+
#attributeGpu(
|
|
464
|
+
frame: IPassFrame,
|
|
465
|
+
offsets: Map<string, number> | undefined,
|
|
466
|
+
allocatedBefore: number,
|
|
467
|
+
): void {
|
|
468
|
+
if (offsets === undefined || offsets.size <= allocatedBefore) return;
|
|
469
|
+
const allocated: string[] = [];
|
|
470
|
+
let index = 0;
|
|
471
|
+
for (const uid of offsets.keys()) {
|
|
472
|
+
index += 1;
|
|
473
|
+
if (index > allocatedBefore) allocated.push(uid);
|
|
474
|
+
}
|
|
475
|
+
if (allocated.length === 0) return;
|
|
476
|
+
const childUids = frame.childUids;
|
|
477
|
+
const own =
|
|
478
|
+
childUids === undefined ? allocated : allocated.filter((uid) => !childUids.includes(uid));
|
|
479
|
+
const parent = this.#stack[this.#stack.length - 1];
|
|
480
|
+
if (parent !== undefined) {
|
|
481
|
+
parent.childUids ??= [];
|
|
482
|
+
parent.childUids.push(...allocated);
|
|
483
|
+
}
|
|
484
|
+
for (const uid of own) this.#recordGpuUid(uid, frame.kind);
|
|
485
|
+
}
|
|
486
|
+
|
|
487
|
+
/** Files one allocated uid under the frame the uid names, dropping the oldest frames over time. */
|
|
488
|
+
#recordGpuUid(uid: string, kind: FramePassKind): void {
|
|
489
|
+
const match = /:f(\d+)$/u.exec(uid);
|
|
490
|
+
if (match === null) return;
|
|
491
|
+
const frame = Number(match[1]);
|
|
492
|
+
const entries = this.#gpuUids.get(frame);
|
|
493
|
+
if (entries === undefined) this.#gpuUids.set(frame, [{ kind, uid }]);
|
|
494
|
+
else entries.push({ kind, uid });
|
|
495
|
+
while (this.#gpuUids.size > GPU_UID_FRAME_LIMIT) {
|
|
496
|
+
const oldest = this.#gpuUids.keys().next().value;
|
|
497
|
+
if (oldest === undefined) break;
|
|
498
|
+
this.#gpuUids.delete(oldest);
|
|
499
|
+
}
|
|
500
|
+
}
|
|
501
|
+
}
|