@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
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { Object3D, Matrix4, Camera, BufferGeometry } 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,13 +82,39 @@ 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
|
}
|
|
@@ -214,6 +248,7 @@ interface IFramePhaseSample {
|
|
|
214
248
|
* convention off does not turn its measurement off.
|
|
215
249
|
*/
|
|
216
250
|
interface IFrameSurfaceState {
|
|
251
|
+
readonly resolutionSubrect?: boolean;
|
|
217
252
|
/** The applied drawing-buffer scale, in `(0, 1]`. */
|
|
218
253
|
readonly resolutionScale: number;
|
|
219
254
|
/**
|
|
@@ -249,16 +284,45 @@ interface IFrameBudgetSummary {
|
|
|
249
284
|
declare const FRAME_GPU_BUCKETS: readonly ["main", "shadow", "other", "compute"];
|
|
250
285
|
type FrameGpuBucket = (typeof FRAME_GPU_BUCKETS)[number];
|
|
251
286
|
/** One frame's GPU milliseconds per bucket; a bucket the device did not resolve is absent. */
|
|
252
|
-
type IFrameGpuBucketSample = Partial<Record<FrameGpuBucket, number
|
|
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
|
+
};
|
|
253
295
|
/**
|
|
254
296
|
* One render-pass kind's submissions across a window, so a change that trades triangles for CPU is
|
|
255
297
|
* visible in the same report as the milliseconds it traded for.
|
|
256
298
|
*/
|
|
257
299
|
interface IFrameBudgetPassSummary {
|
|
258
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>>>;
|
|
259
313
|
/** Frames in the window that submitted a pass of this kind. */
|
|
260
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
|
+
*/
|
|
261
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;
|
|
262
326
|
}
|
|
263
327
|
/**
|
|
264
328
|
* One reported window of the frame meter.
|
|
@@ -275,10 +339,21 @@ interface IFrameBudgetPassSummary {
|
|
|
275
339
|
* it were a player's — `threenative-playtest perf` refuses to (`TN_PERF_VIRTUAL_DISPLAY`).
|
|
276
340
|
*/
|
|
277
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
|
+
};
|
|
278
351
|
/** 1 for the first reported window, incrementing thereafter. */
|
|
279
352
|
readonly window: number;
|
|
280
353
|
/** Loop frames counted in this window, hitches excluded — one per present on the web. */
|
|
281
354
|
readonly frames: number;
|
|
355
|
+
/** Fixed simulation ticks in this window multiplied by the loop's step, when supplied. */
|
|
356
|
+
readonly simulatedSeconds?: number;
|
|
282
357
|
/** Frames excluded from the window because their present gap exceeded `hitchMs`. */
|
|
283
358
|
readonly hitches: number;
|
|
284
359
|
/**
|
|
@@ -345,6 +420,18 @@ interface IFrameBudgetWindow {
|
|
|
345
420
|
*/
|
|
346
421
|
readonly targetFps?: number;
|
|
347
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
|
+
};
|
|
348
435
|
/**
|
|
349
436
|
* GPU milliseconds per resolved frame in this window, from `timestamp-query`, summarised like a
|
|
350
437
|
* phase — mean/p50/p95/p99/max over the frames the device actually reported.
|
|
@@ -362,6 +449,13 @@ interface IFrameBudgetWindow {
|
|
|
362
449
|
* every frame is stale reports `gpu` absent rather than the last reading looking current.
|
|
363
450
|
*/
|
|
364
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;
|
|
365
459
|
/**
|
|
366
460
|
* The window mean of `gpu`, when present. The scalar the resolution scaler reads.
|
|
367
461
|
*
|
|
@@ -369,6 +463,11 @@ interface IFrameBudgetWindow {
|
|
|
369
463
|
* one series rather than a second instantaneous read.
|
|
370
464
|
*/
|
|
371
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
|
+
};
|
|
372
471
|
/** Age of the most recent resolved GPU timestamp in Three.js frame IDs; absent means unobservable. */
|
|
373
472
|
readonly gpuAgeFrames?: number;
|
|
374
473
|
/**
|
|
@@ -385,27 +484,58 @@ interface IFrameBudgetWindow {
|
|
|
385
484
|
readonly gpuOther?: number;
|
|
386
485
|
readonly gpuCompute?: number;
|
|
387
486
|
/**
|
|
388
|
-
* The
|
|
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.
|
|
389
497
|
*
|
|
390
|
-
*
|
|
391
|
-
*
|
|
392
|
-
*
|
|
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.
|
|
509
|
+
*
|
|
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
|
|
393
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.
|
|
394
516
|
*/
|
|
395
517
|
readonly counters?: {
|
|
396
518
|
readonly hostCalls?: IFrameBudgetSummary;
|
|
397
519
|
readonly gpuBytes?: IFrameBudgetSummary;
|
|
398
520
|
readonly jsAllocBytes?: IFrameBudgetSummary;
|
|
521
|
+
readonly simulationTick?: number;
|
|
399
522
|
};
|
|
400
523
|
}
|
|
524
|
+
interface IFrameBudgetSimulation {
|
|
525
|
+
readonly tick: () => number;
|
|
526
|
+
readonly step: number;
|
|
527
|
+
}
|
|
401
528
|
interface IFrameBudgetOptions {
|
|
402
|
-
/**
|
|
529
|
+
/** Simulation ticks per report window when a clock is supplied, otherwise presented frames. Default 300. */
|
|
403
530
|
readonly reportEvery?: number;
|
|
531
|
+
/** Minimum measured rendered frames per report window. Default 1. */
|
|
532
|
+
readonly minFrames?: number;
|
|
533
|
+
readonly simulation?: IFrameBudgetSimulation;
|
|
404
534
|
/** A present gap at or above this is a hitch, not a frame. Default 2000 ms. */
|
|
405
535
|
readonly hitchMs?: number;
|
|
406
536
|
/** Ring capacity per series. Default 1024. */
|
|
407
537
|
readonly capacity?: number;
|
|
408
|
-
/** 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. */
|
|
409
539
|
readonly report?: (line: string) => void;
|
|
410
540
|
/** Wall clock for hitch markers. Default `Date.now`. */
|
|
411
541
|
readonly wallClock?: () => number;
|
|
@@ -453,11 +583,13 @@ interface IFrameBudgetOptions {
|
|
|
453
583
|
*
|
|
454
584
|
* The caller is the frame loop; the sequence per frame is
|
|
455
585
|
* `beginFrame` → `markSimulationEnd` → (`addRender` / `addOverlay` / `addUi`) → `endFrame`.
|
|
456
|
-
* 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.
|
|
457
588
|
*/
|
|
458
589
|
declare class FrameBudget {
|
|
459
590
|
#private;
|
|
460
591
|
readonly reportEvery: number;
|
|
592
|
+
readonly minFrames: number;
|
|
461
593
|
readonly hitchMs: number;
|
|
462
594
|
constructor(options?: IFrameBudgetOptions);
|
|
463
595
|
/**
|
|
@@ -465,10 +597,31 @@ declare class FrameBudget {
|
|
|
465
597
|
* clock, which is not the same as `nowMs` and is what the interval between frames comes from.
|
|
466
598
|
* @param nowMs the monotonic clock at callback entry.
|
|
467
599
|
*/
|
|
600
|
+
dispose(): void;
|
|
468
601
|
beginFrame(timestampMs: number, nowMs: number): void;
|
|
469
602
|
/** The boundary between the fixed-step simulation and everything the render phase does. */
|
|
470
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;
|
|
471
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;
|
|
472
625
|
addOverlay(ms: number): void;
|
|
473
626
|
addUi(ms: number): void;
|
|
474
627
|
/**
|
|
@@ -484,6 +637,8 @@ declare class FrameBudget {
|
|
|
484
637
|
* Once per frame. A window with no reading at all reports `gpu` absent, never a zero.
|
|
485
638
|
*/
|
|
486
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;
|
|
487
642
|
/**
|
|
488
643
|
* Records where one resolved frame's GPU time went, from the per-pass timestamp split.
|
|
489
644
|
*
|
|
@@ -499,6 +654,10 @@ declare class FrameBudget {
|
|
|
499
654
|
* At most one call per frame; a second replaces the first rather than summing, because the
|
|
500
655
|
* counter's own reader already returns the frame's totals and summing two reads of one frame
|
|
501
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.
|
|
502
661
|
*/
|
|
503
662
|
addCounters(counters: IFrameCounters): void;
|
|
504
663
|
/**
|
|
@@ -600,8 +759,22 @@ interface IPipelineCensusEvent {
|
|
|
600
759
|
/** Promise latency is retained as latency, never labelled native compiler time. */
|
|
601
760
|
readonly promiseMs?: number;
|
|
602
761
|
readonly error?: string;
|
|
762
|
+
/** Number of distinct Three node-builder states first observed during this render-object call. */
|
|
763
|
+
readonly nodeBuilds?: number;
|
|
603
764
|
/** Whether this event settled before the first present boundary. */
|
|
604
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;
|
|
605
778
|
}
|
|
606
779
|
interface IPipelineCensusCounts {
|
|
607
780
|
readonly lookups: number;
|
|
@@ -612,6 +785,7 @@ interface IPipelineCensusCounts {
|
|
|
612
785
|
readonly uniquePipelines: number;
|
|
613
786
|
readonly recordedEvents: number;
|
|
614
787
|
readonly droppedEvents: number;
|
|
788
|
+
readonly nodeBuilds: number;
|
|
615
789
|
/**
|
|
616
790
|
* Every creation seen at the device, including those attributed to a backend event. Absent
|
|
617
791
|
* when the device could not be observed at all, so no reader mistakes silence for zero.
|
|
@@ -645,8 +819,26 @@ interface IPipelineCensus {
|
|
|
645
819
|
readonly boundaryMs: number;
|
|
646
820
|
readonly eventsSettled: number;
|
|
647
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
|
+
}[];
|
|
648
839
|
readonly counts: IPipelineCensusCounts;
|
|
649
840
|
readonly events: readonly IPipelineCensusEvent[];
|
|
841
|
+
readonly nodeBuilds?: readonly IPipelineNodeBuild[];
|
|
650
842
|
readonly incompleteReasons: readonly string[];
|
|
651
843
|
}
|
|
652
844
|
interface IPipelineCensusOptions {
|
|
@@ -660,11 +852,14 @@ interface IPipelineCensusOptions {
|
|
|
660
852
|
}
|
|
661
853
|
interface IRendererHookTarget {
|
|
662
854
|
backend?: unknown;
|
|
855
|
+
/** Three's renderer-owned node manager; absent on the WebGL2 renderer. */
|
|
856
|
+
_nodes?: unknown;
|
|
663
857
|
renderObject?: (...args: unknown[]) => unknown;
|
|
664
858
|
}
|
|
665
859
|
/**
|
|
666
860
|
* Create and install a bounded census. The returned object is intentionally small: renderers own
|
|
667
|
-
* lifecycle and callers only need `snapshot()`, `withRenderObject()`, and
|
|
861
|
+
* lifecycle and callers only need `snapshot()`, `withRenderObject()`, and the two lifecycle
|
|
862
|
+
* boundaries.
|
|
668
863
|
*/
|
|
669
864
|
declare function createPipelineCensus(options: IPipelineCensusOptions): PipelineCensus;
|
|
670
865
|
declare class PipelineCensus {
|
|
@@ -678,11 +873,110 @@ declare class PipelineCensus {
|
|
|
678
873
|
dispose(): void;
|
|
679
874
|
/** Wrap Three's public render-object method so compileAsync retains the authored pass id. */
|
|
680
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;
|
|
681
880
|
/** Mark the first renderer render call as the first-present boundary. */
|
|
682
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;
|
|
683
886
|
snapshot(): IPipelineCensus;
|
|
684
887
|
}
|
|
685
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
|
+
|
|
686
980
|
/** The marker shared by alpha-antialiasing logs, playtests, and native diagnostics. */
|
|
687
981
|
declare const ALPHA_ANTIALIASING_MARKER = "TN_ALPHA_ANTIALIASING";
|
|
688
982
|
interface IAlphaAntialiasingReport {
|
|
@@ -697,6 +991,27 @@ interface IAlphaAntialiasingReport {
|
|
|
697
991
|
readonly materials: number;
|
|
698
992
|
}
|
|
699
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
|
+
|
|
700
1015
|
/** The output name shared by the scene pass and temporal consumers. */
|
|
701
1016
|
declare const VELOCITY_OUTPUT_NAME = "velocity";
|
|
702
1017
|
/**
|
|
@@ -706,6 +1021,8 @@ declare const VELOCITY_OUTPUT_NAME = "velocity";
|
|
|
706
1021
|
* without making the game depend on either implementation.
|
|
707
1022
|
*/
|
|
708
1023
|
interface IVelocityRenderPass {
|
|
1024
|
+
/** Physical attachments on Three passes; structural adapters may own them elsewhere. */
|
|
1025
|
+
readonly renderTarget?: Pick<RenderTarget, "textures" | "dispose">;
|
|
709
1026
|
getMRT(): MRTNode | null;
|
|
710
1027
|
getTextureNode(name?: string): Node;
|
|
711
1028
|
setMRT(value: MRTNode | null): unknown;
|
|
@@ -736,6 +1053,17 @@ declare function velocityTexture(pass: IVelocityRenderPass): Node;
|
|
|
736
1053
|
* @situation hand the provisioned velocity source through a composed temporal graph
|
|
737
1054
|
*/
|
|
738
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
|
+
}
|
|
739
1067
|
/**
|
|
740
1068
|
* Captures instance matrices at the framework's pre-render boundary and enables previous data on
|
|
741
1069
|
* every renderable in the graph. The previous snapshot is never the array the game writes next.
|
|
@@ -800,11 +1128,11 @@ interface IRenderChainVelocityResult {
|
|
|
800
1128
|
interface IRenderChainRenderer {
|
|
801
1129
|
readonly kind: RendererKind;
|
|
802
1130
|
readonly raw: unknown;
|
|
803
|
-
clearOutputNode?(): void;
|
|
1131
|
+
clearOutputNode?(expectedNode?: unknown): void;
|
|
804
1132
|
/** Internal renderer seam used to turn on core-owned previous-frame bookkeeping for active temporal stages. */
|
|
805
1133
|
setRenderChainVelocityEnabled?(enabled: boolean): void;
|
|
806
1134
|
/** Install a graph and identify the authored world pass that follows the rendered scene root. */
|
|
807
|
-
setOutputNode
|
|
1135
|
+
setOutputNode: RenderOutputSetter;
|
|
808
1136
|
}
|
|
809
1137
|
/** Quality values are algorithm parameters, not appearance values. Templates own the latter. */
|
|
810
1138
|
declare const RENDER_CHAIN_TIERS: {
|
|
@@ -832,6 +1160,12 @@ declare const RENDER_CHAIN_TIERS: {
|
|
|
832
1160
|
interface IRenderChainVelocityRequest {
|
|
833
1161
|
/** The scene pass that owns the shared velocity output. */
|
|
834
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;
|
|
835
1169
|
/** Treat the renderer's MRT velocity output as provisioned. */
|
|
836
1170
|
mrt?: boolean;
|
|
837
1171
|
/** Treat objects carrying `userData.useVelocity === true` as provisioned. */
|
|
@@ -856,16 +1190,32 @@ interface IRenderChainRequest {
|
|
|
856
1190
|
interface IRenderChainStageContext {
|
|
857
1191
|
readonly tier: RenderChainTier;
|
|
858
1192
|
readonly velocity: IRenderChainVelocityReport;
|
|
1193
|
+
/** Mutable target fractions supplied to generated stages for sub-rectangle sampling. */
|
|
1194
|
+
readonly resolutionSubrect?: IResolutionTextureView;
|
|
859
1195
|
/** TSL source handed to temporal stages when the request owns a scene pass. */
|
|
860
1196
|
readonly velocityNode?: Node;
|
|
861
1197
|
readonly quality: (typeof RENDER_CHAIN_TIERS)[RenderChainTier];
|
|
862
1198
|
}
|
|
863
1199
|
interface IRenderChainStage {
|
|
1200
|
+
readonly supportsResolutionSubrect?: boolean;
|
|
864
1201
|
readonly name: RenderChainStageId;
|
|
865
1202
|
/** Place an authored stage immediately before this built-in or supplied stage. */
|
|
866
1203
|
readonly before?: RenderChainStageId;
|
|
867
1204
|
/** Place an authored stage immediately after this built-in or supplied stage. */
|
|
868
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;
|
|
869
1219
|
readonly build: (input: unknown, context: IRenderChainStageContext) => unknown;
|
|
870
1220
|
/** Stages below this tier are named as dropped instead of silently changing the graph. */
|
|
871
1221
|
readonly minimumTier?: RenderChainTier;
|
|
@@ -913,6 +1263,7 @@ interface IRenderChainBudgetWindow {
|
|
|
913
1263
|
};
|
|
914
1264
|
}
|
|
915
1265
|
interface IRenderChainOptions {
|
|
1266
|
+
readonly resolutionSubrect?: IResolutionSubrect;
|
|
916
1267
|
readonly renderer: IRenderChainRenderer;
|
|
917
1268
|
readonly input?: unknown;
|
|
918
1269
|
/** Explicit scene pass for output retargeting; avoids traversing a composed graph to find it. */
|
|
@@ -962,7 +1313,39 @@ declare class RenderChain {
|
|
|
962
1313
|
dispose(): void;
|
|
963
1314
|
}
|
|
964
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
|
+
|
|
965
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);
|
|
966
1349
|
/**
|
|
967
1350
|
* Put transient meshes through the renderer's first-use shader path during loading.
|
|
968
1351
|
*
|
|
@@ -1003,6 +1386,12 @@ interface IRendererLike {
|
|
|
1003
1386
|
readonly compileCount?: number;
|
|
1004
1387
|
/** The bounded, fail-closed pipeline observation for this renderer, when enabled. */
|
|
1005
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;
|
|
1006
1395
|
/**
|
|
1007
1396
|
* What alpha antialiasing did with the multisampled surface, and why, when it did nothing.
|
|
1008
1397
|
*
|
|
@@ -1030,7 +1419,23 @@ interface IRendererLike {
|
|
|
1030
1419
|
* exposes the same four `adapter.info` fields, so the same read works on every target.
|
|
1031
1420
|
*/
|
|
1032
1421
|
readonly softwareAdapter?: string;
|
|
1033
|
-
|
|
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;
|
|
1034
1439
|
/**
|
|
1035
1440
|
* Creates the GPU buffers these geometries draw from, through the backend's own attribute path,
|
|
1036
1441
|
* and reports how many it created.
|
|
@@ -1042,6 +1447,34 @@ interface IRendererLike {
|
|
|
1042
1447
|
* draw uploads exactly as it did before.
|
|
1043
1448
|
*/
|
|
1044
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>;
|
|
1045
1478
|
/**
|
|
1046
1479
|
* Copies one GPU storage attribute back to the CPU, asynchronously.
|
|
1047
1480
|
*
|
|
@@ -1049,14 +1482,29 @@ interface IRendererLike {
|
|
|
1049
1482
|
* must cast through `.raw` to read its own simulation will either not read it or read it wrong.
|
|
1050
1483
|
* The copy is asynchronous by nature — the caller gets the bytes some frames after the frame
|
|
1051
1484
|
* that produced them, and `GPUReadback` is what turns that latency into a reported number
|
|
1052
|
-
* 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.
|
|
1053
1487
|
*/
|
|
1054
|
-
readback(attribute: unknown): Promise<ArrayBuffer>;
|
|
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.
|
|
1496
|
+
*/
|
|
1497
|
+
scenePassDepth?(): {
|
|
1498
|
+
readonly texture: DepthTexture;
|
|
1499
|
+
readonly width: number;
|
|
1500
|
+
readonly height: number;
|
|
1501
|
+
readonly samples?: number;
|
|
1502
|
+
} | undefined;
|
|
1055
1503
|
render(scene: Object3D, camera: Camera): void;
|
|
1056
1504
|
/** Draws after the world without clearing or passing through the world's output pipeline. */
|
|
1057
1505
|
renderOverlay(scene: Object3D, camera: Camera): void;
|
|
1058
|
-
/**
|
|
1059
|
-
clearOutputNode?(): void;
|
|
1506
|
+
/** Legacy input-filtered clear; use an installation receipt for same-node replacement safety. */
|
|
1507
|
+
clearOutputNode?(expectedNode?: unknown): void;
|
|
1060
1508
|
/** Creates the core-owned chain seam without making generated render source import the package. */
|
|
1061
1509
|
createRenderChain?: (options: Omit<IRenderChainOptions, "renderer">) => RenderChain;
|
|
1062
1510
|
/** Feeds automatic render-chain tiers the completed frame-budget window. */
|
|
@@ -1068,7 +1516,8 @@ interface IRendererLike {
|
|
|
1068
1516
|
/** Internal callback used by RenderChain; games should request velocity through the chain. */
|
|
1069
1517
|
setRenderChainVelocityEnabled?: (enabled: boolean) => void;
|
|
1070
1518
|
/** Installs a graph; pass the authored world pass when the graph contains auxiliary passes. */
|
|
1071
|
-
setOutputNode
|
|
1519
|
+
setOutputNode: RenderOutputSetter;
|
|
1520
|
+
createResolutionSubrect?: () => IResolutionSubrect;
|
|
1072
1521
|
setSize(width: number, height: number, updateStyle?: boolean): void;
|
|
1073
1522
|
/**
|
|
1074
1523
|
* The GPU time the last resolved frame actually cost, in milliseconds, or `undefined` when the
|
|
@@ -1095,6 +1544,14 @@ interface IRendererLike {
|
|
|
1095
1544
|
readonly frame: number;
|
|
1096
1545
|
readonly ms: number;
|
|
1097
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;
|
|
1098
1555
|
/**
|
|
1099
1556
|
* GPU milliseconds of the last resolved compute frame, when the adapter reports one.
|
|
1100
1557
|
*
|
|
@@ -1104,6 +1561,8 @@ interface IRendererLike {
|
|
|
1104
1561
|
* frame that ran no compute.
|
|
1105
1562
|
*/
|
|
1106
1563
|
gpuComputeMs?(): number | undefined;
|
|
1564
|
+
/** Consume one fresh timestamped pyramid build, including its depth resolve; absent until resolved. */
|
|
1565
|
+
gpuPyramidMs?(): number | undefined;
|
|
1107
1566
|
/**
|
|
1108
1567
|
* The main render pass's GPU milliseconds, smoothed over fresh resolved samples, or `undefined`
|
|
1109
1568
|
* while no reading is fresh.
|
|
@@ -1120,6 +1579,14 @@ interface IRendererLike {
|
|
|
1120
1579
|
* frame by `game.ts`; `ms` is `undefined` when the frame attributed no main-pass reading.
|
|
1121
1580
|
*/
|
|
1122
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;
|
|
1123
1590
|
/** Starts a resolve of the GPU timestamps for the frames drawn since the last call. */
|
|
1124
1591
|
resolveGpuFrame(): void;
|
|
1125
1592
|
/**
|
|
@@ -1189,4 +1656,4 @@ interface IRendererOptions {
|
|
|
1189
1656
|
}>) => unknown;
|
|
1190
1657
|
}
|
|
1191
1658
|
|
|
1192
|
-
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 };
|