@threenative/core 0.3.11 → 0.3.13
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/README.md +1 -1
- package/capabilities.json +1988 -204
- package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
- package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
- package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
- package/dist/chunk-4SRAQFTU.js +133 -0
- package/dist/chunk-CFGTPFUH.js +231 -0
- package/dist/chunk-DIPIJICH.js +8916 -0
- package/dist/chunk-EEABDLUC.js +2237 -0
- package/dist/chunk-EFWZWLPY.js +1895 -0
- package/dist/chunk-GXY7B3JG.js +46 -0
- package/dist/chunk-GYUZJQ7U.js +280 -0
- package/dist/chunk-H4J6IAJE.js +504 -0
- package/dist/chunk-KIRUKTBQ.js +187 -0
- package/dist/chunk-QWJEMUUT.js +94 -0
- package/dist/chunk-SV4QVUTQ.js +31 -0
- package/dist/chunk-U4YHUKKL.js +615 -0
- package/dist/chunk-VP43GIWW.js +18 -0
- package/dist/chunk-XDTZ4QMO.js +160 -0
- package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
- package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
- package/dist/hot.d.ts +5 -4
- package/dist/hot.js +5 -52
- package/dist/index.d.ts +633 -1351
- package/dist/index.js +12873 -23068
- package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
- package/dist/playtest.d.ts +5 -4
- package/dist/playtest.js +25 -75
- package/dist/quality-BYqKGAwo.d.ts +868 -0
- package/dist/react-css.js +1 -215
- package/dist/react.d.ts +3 -2
- package/dist/render-environment.d.ts +170 -0
- package/dist/render-environment.js +352 -0
- package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
- package/dist/spells/index.d.ts +643 -0
- package/dist/spells/index.js +1558 -0
- package/dist/spells/ultra/index.d.ts +1600 -0
- package/dist/spells/ultra/index.js +6804 -0
- package/dist/terrain-jobs-worker.js +1 -123
- package/dist/two-sided-foliage-W523J3UM.js +1 -0
- package/dist/ui-layer.js +6 -384
- package/dist/worker.js +13 -43
- package/dist/world.d.ts +988 -268
- package/dist/world.js +17464 -18290
- package/mcp/animation-server.mjs +1 -1
- package/mcp/animation.mjs +2 -3
- package/mcp/engine-server.mjs +245 -52
- package/mcp/servers.mjs +10 -3
- package/mcp/terrain.mjs +8 -0
- package/package.json +19 -7
- package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
- package/patches/three@0.187.0.patch +2004 -407
- package/src/animation-batch.ts +193 -0
- package/src/animation-layers.ts +7 -3
- package/src/animation.ts +209 -29
- package/src/asset-cache.ts +3 -3
- package/src/asset-memo.ts +202 -0
- package/src/assets.ts +437 -125
- package/src/auto-batch.ts +190 -44
- package/src/card-lod.ts +152 -0
- package/src/compressed-texture-preparation.ts +1008 -0
- package/src/compute-driven.ts +1 -1
- package/src/config.ts +8 -0
- package/src/debug.ts +103 -22
- package/src/dev-global.ts +54 -0
- package/src/engine-hooks.ts +37 -0
- package/src/frame-budget.ts +50 -23
- package/src/game-boot-phase.ts +269 -0
- package/src/game-dev-tools.ts +86 -0
- package/src/game-frame-loop.ts +958 -0
- package/src/game-renderer-metrics.ts +77 -0
- package/src/game-startup.ts +1076 -0
- package/src/game-ui.ts +84 -0
- package/src/game-validate.ts +70 -0
- package/src/game.ts +198 -2264
- package/src/gamepad-mappings.ts +269 -0
- package/src/generated/console-markers.ts +13 -0
- package/src/geometry-capture.ts +28 -4
- package/src/gpu-readings.ts +98 -0
- package/src/gpu-scene-bvh.ts +149 -36
- package/src/hot.ts +4 -7
- package/src/index.ts +141 -9
- package/src/input.ts +237 -25
- package/src/instanced-batch-lod.ts +3 -8
- package/src/interpolation.ts +171 -40
- package/src/launch-diagnostics.ts +22 -12
- package/src/look/ao-admission.ts +25 -0
- package/src/look/auto-exposure.ts +5 -16
- package/src/look/default-tone-mapping.ts +41 -5
- package/src/look/filmic-tone-mapping.ts +15 -13
- package/src/look/local-exposure.ts +2 -7
- package/src/look/look-diagnostics.ts +3 -3
- package/src/look/quad-pass.ts +21 -0
- package/src/look/quality.ts +14 -5
- package/src/look/unreal-bloom.ts +4 -13
- package/src/look/world-environment.ts +113 -103
- package/src/loop.ts +29 -0
- package/src/merge-parts.ts +20 -24
- package/src/model-lod.ts +139 -17
- package/src/particle-kinds.ts +515 -0
- package/src/particle-significance.ts +12 -0
- package/src/particles.ts +19 -10
- package/src/picking.ts +17 -3
- package/src/platform.ts +23 -4
- package/src/playtest.ts +27 -1
- package/src/profiling/FrameStages.ts +5 -6
- package/src/profiling/Spans.ts +3 -17
- package/src/profiling/debug-telemetry.ts +2 -6
- package/src/profiling/render-list-validate.ts +6 -15
- package/src/projection-apply.ts +4 -1
- package/src/projection-marker.ts +2 -1
- package/src/projection-plan.ts +9 -6
- package/src/quiet-markers.ts +3 -10
- package/src/render/cpu-bvh.ts +100 -0
- package/src/render/depth-pyramid.ts +6 -14
- package/src/render/environment/environmentContribution.ts +202 -0
- package/src/render/environment/environmentRadiance.ts +44 -0
- package/src/render/environment/environmentSampleCache.ts +56 -0
- package/src/render/environment/environmentSampling.ts +201 -0
- package/src/render/environment/environmentSnapshot.ts +71 -0
- package/src/render/environment/gate.ts +57 -0
- package/src/render/mesh-pool.ts +4 -20
- package/src/render/probe-trace.ts +872 -0
- package/src/render/probe-volume.ts +780 -34
- package/src/render/radiance-cache.ts +17 -0
- package/src/render/resolution-subrect.ts +2 -0
- package/src/render/rough-diffuse.ts +46 -12
- package/src/render/soft-shadow.ts +27 -12
- package/src/render/virtual-shadow-adaptive.ts +55 -0
- package/src/render/virtual-shadow-casters.ts +175 -0
- package/src/render/virtual-shadow-layers.ts +76 -0
- package/src/render/virtual-shadow-level.ts +224 -0
- package/src/render/virtual-shadow-markers.ts +193 -0
- package/src/render/virtual-shadow-options.ts +370 -0
- package/src/render/virtual-shadow-pages.ts +5 -0
- package/src/render/virtual-shadow-partial.ts +13 -0
- package/src/render/virtual-shadow.ts +231 -1008
- package/src/render/world-impostor-surface.ts +402 -40
- package/src/render/world-impostor.ts +5 -2
- package/src/render-camera-cull.ts +98 -3
- package/src/render-environment.ts +41 -0
- package/src/render-pass-budget.ts +34 -7
- package/src/renderProjection.ts +22 -0
- package/src/renderer-config.ts +36 -0
- package/src/renderer-facts.ts +37 -0
- package/src/renderer.ts +144 -65
- package/src/resolution-scaler.ts +3 -2
- package/src/scene-entry-inspectors.ts +61 -0
- package/src/snow-field.ts +2 -1
- package/src/spells/cast-pool.ts +361 -0
- package/src/spells/index.ts +177 -0
- package/src/spells/mechanisms.ts +295 -0
- package/src/spells/reaction-field.ts +415 -0
- package/src/spells/spell-lights.ts +139 -0
- package/src/spells/spell-world.ts +187 -0
- package/src/spells/spell.ts +397 -0
- package/src/spells/spells.ts +283 -0
- package/src/spells/ultra/engine/camera.ts +184 -0
- package/src/spells/ultra/engine/quality.ts +96 -0
- package/src/spells/ultra/index.ts +52 -0
- package/src/spells/ultra/main.ts +305 -0
- package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
- package/src/spells/ultra/spells/cast.ts +233 -0
- package/src/spells/ultra/spells/fire.ts +1267 -0
- package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
- package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
- package/src/spells/ultra/vfx/FxTarget.ts +61 -0
- package/src/spells/ultra/vfx/GroundField.ts +1399 -0
- package/src/spells/ultra/vfx/Particles.ts +1475 -0
- package/src/spells/ultra/vfx/Ribbons.ts +645 -0
- package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
- package/src/spells/ultra/vfx/Volumes.ts +489 -0
- package/src/spells/ultra/vfx/common.ts +1195 -0
- package/src/spells/ultra/vfx/noise.ts +441 -0
- package/src/startup-offscreen-bytes.ts +78 -0
- package/src/startup-readiness.ts +128 -34
- package/src/static-transform.ts +25 -19
- package/src/streamed-textures.ts +112 -0
- package/src/streaming.ts +68 -4
- package/src/texture-streaming.ts +331 -0
- package/src/version.ts +1 -1
- package/src/warmup.ts +56 -8
- package/src/water-surface.ts +9 -3
- package/src/worker.ts +12 -2
- package/src/world-bundle-safety.ts +446 -0
- package/src/world-cell-batches.ts +1178 -0
- package/src/world-cell-chunks.ts +1128 -0
- package/src/world-cell-data.ts +995 -0
- package/src/world-cell-impostors.ts +1461 -0
- package/src/world-cell-lod-bias.ts +151 -0
- package/src/world-cell-models.ts +1074 -0
- package/src/world-cell-options.ts +177 -0
- package/src/world-cell-placements.ts +798 -0
- package/src/world-cell-prewarm.ts +592 -0
- package/src/world-cell-readiness.ts +357 -0
- package/src/world-cell-records.ts +401 -0
- package/src/world-cell-render-bundles.ts +459 -0
- package/src/world-cell-render-gpu-dress.ts +710 -0
- package/src/world-cell-render-main-cull.ts +540 -0
- package/src/world-cell-render-shadow-claims.ts +198 -0
- package/src/world-cell-render-util.ts +259 -0
- package/src/world-cell-render.ts +1501 -0
- package/src/world-cell-residency.ts +754 -0
- package/src/world-cell-stale.ts +238 -0
- package/src/world-cells.ts +1335 -10418
- package/src/world-chunk-shadow.ts +308 -0
- package/src/world-collar.ts +315 -0
- package/src/world-gpu-flags.ts +131 -0
- package/src/world-gpu-readback.ts +881 -0
- package/src/world-gpu-reference.ts +524 -0
- package/src/world-gpu-scene.ts +256 -2286
- package/src/world-gpu-shadow.ts +203 -0
- package/src/world-gpu-types.ts +409 -0
- package/src/world-gpu-validation.ts +518 -0
- package/src/world-heightfield.ts +802 -0
- package/src/world-load-limiter.ts +111 -0
- package/src/world-model-sections.ts +80 -0
- package/src/world-noise.ts +241 -0
- package/src/world-package.ts +42 -0
- package/src/world-region.ts +1 -1
- package/src/world-river-ribbon.ts +282 -0
- package/src/world-root-frame.ts +39 -0
- package/src/world-shore-field.ts +91 -0
- package/src/world-static-pose.ts +163 -0
- package/src/world-surface-sampler.ts +48 -0
- package/src/world-terrain-splat.ts +361 -153
- package/src/world-tile-budget.ts +249 -0
- package/src/world-tile-geometry.ts +469 -0
- package/src/world-tile-lod.ts +408 -0
- package/src/world-tile-observation.ts +566 -0
- package/src/world-tile-stitch.ts +166 -0
- package/src/world-tiles.ts +247 -1755
- package/src/world-validate.ts +6 -14
- package/src/world-warm.ts +51 -0
- package/src/world-water-bodies.ts +359 -0
- package/src/world.ts +48 -741
|
@@ -0,0 +1,370 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a {@link VirtualShadowNode} is asked for, what it reports, and the default of every knob.
|
|
3
|
+
*
|
|
4
|
+
* Types and defaults only: the node owns the mechanism these describe.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Options for {@link VirtualShadowNode}. Every value is a mechanism parameter; the light's own
|
|
9
|
+
* `shadow` keeps bias, normalBias, intensity, map type and filter, exactly as with a stock shadow.
|
|
10
|
+
*/
|
|
11
|
+
export interface IVirtualShadowOptions {
|
|
12
|
+
/**
|
|
13
|
+
* Half-width of each clip level's window in world units, finest first and strictly
|
|
14
|
+
* increasing. Default `[16, 48, 144]`: three windows, each three times wider than the last.
|
|
15
|
+
*/
|
|
16
|
+
readonly clipExtents?: readonly number[];
|
|
17
|
+
/**
|
|
18
|
+
* The widest step between two levels, default 2: where `clipExtents` jump further, levels are
|
|
19
|
+
* inserted at even ratios, as UE 5.8.3 doubles every clipmap level (`GetLevelRadius`,
|
|
20
|
+
* Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapClipmap.cpp:175-179). A
|
|
21
|
+
* receiver crossing a level edge then changes texel size by at most this ratio: across `[24, 320]`
|
|
22
|
+
* the texel grew 13 times at once and every tree on the edge flipped from self-shadowed to flat
|
|
23
|
+
* lit. Per-level lists (`mapSize`, `refreshStep`, `selectionGuard`, `invalidationDelay`) give an
|
|
24
|
+
* inserted level the value of the authored level it leads into. `Infinity` keeps the authored
|
|
25
|
+
* levels as they are, and `TN_VIRTUAL_SHADOW_OVERRIDE` reports it.
|
|
26
|
+
*/
|
|
27
|
+
readonly maxLevelRatio?: number;
|
|
28
|
+
/**
|
|
29
|
+
* Resolution bias in stops, default 0. Mirrors Unreal's
|
|
30
|
+
* `r.Shadow.Virtual.ResolutionLodBiasDirectional`; a quality tier sets it. With the default map
|
|
31
|
+
* sizes each stop doubles every level's texel: `-1` halves it (twice the resolution), `-1.5` is
|
|
32
|
+
* 2.83 times finer, a positive bias coarsens it. With an authored `mapSize` the finest window
|
|
33
|
+
* scales by `2 ** bias` instead and every coarser level keeps its extent; a bias that would push
|
|
34
|
+
* that window past the next level throws.
|
|
35
|
+
*/
|
|
36
|
+
readonly resolutionLodBiasDirectional?: number;
|
|
37
|
+
/**
|
|
38
|
+
* Texels per level edge: one number for every level, or one per level, finest first. Default:
|
|
39
|
+
* Unreal's clipmap rule, measured on the camera and viewport that first read the shadow, so a
|
|
40
|
+
* receiver's texel is at most `2^(1 + bias)` of its own screen pixels (`clipmapMapSizes`). Set it to
|
|
41
|
+
* hold fixed sizes.
|
|
42
|
+
*/
|
|
43
|
+
readonly mapSize?: number | readonly number[];
|
|
44
|
+
/**
|
|
45
|
+
* The page budget of the default map sizes, in 128² pages over all levels, default 4096 (Unreal's
|
|
46
|
+
* `r.Shadow.Virtual.MaxPhysicalPages` at Epic). Sizes over it raise the bias until they fit.
|
|
47
|
+
*/
|
|
48
|
+
readonly maxPhysicalPages?: number;
|
|
49
|
+
/**
|
|
50
|
+
* Texels per edge of each level's mover map — the map tracked casters draw into every frame.
|
|
51
|
+
* Default: `mapSize`, the cached levels' own density, so a caster keeps the edge it had at rest
|
|
52
|
+
* while it moves and does not pop to a crisper one when it settles. Lower it to buy back fill
|
|
53
|
+
* on a weak GPU; the soft edge it costs is on the mover only.
|
|
54
|
+
*/
|
|
55
|
+
readonly moverMapSize?: number;
|
|
56
|
+
/**
|
|
57
|
+
* Fraction of a level's extent inside which a fragment still selects that level, `(0, 1]`,
|
|
58
|
+
* default 0.9 — the outer ring falls through to the next level so the edge is never sampled.
|
|
59
|
+
* `selectionGuard` minus `refreshStep`, since a window trails its centre by that much. One value
|
|
60
|
+
* for every level, or one per level finest first, the last entry standing in for the rest.
|
|
61
|
+
*/
|
|
62
|
+
readonly selectionGuard?: number | readonly number[];
|
|
63
|
+
/**
|
|
64
|
+
* Fraction of a level's extent its window may trail the followed centre by before it re-renders,
|
|
65
|
+
* `[0, selectionGuard)`, default 0.125 — `refreshStep: 0` keeps the old one-texel step. The step
|
|
66
|
+
* is rounded to a whole number of that level's texels, so a walking camera re-renders a level
|
|
67
|
+
* ~`1/refreshStep` times less often while the shadow texels stay on one fixed world grid. Costs
|
|
68
|
+
* that much of `selectionGuard`, which it is already reduced by, so a window never reaches past
|
|
69
|
+
* the trailing edge of a map rendered before the centre moved. One value for every level, or one
|
|
70
|
+
* per level finest first, the last entry standing in for the rest — the fine level is the one a
|
|
71
|
+
* walking camera re-renders most, so it is the one that wants the larger step.
|
|
72
|
+
*/
|
|
73
|
+
readonly refreshStep?: number | readonly number[];
|
|
74
|
+
/**
|
|
75
|
+
* Let a level buy itself a wider `refreshStep` out of what its own last render cost, default true.
|
|
76
|
+
*
|
|
77
|
+
* A level render is a whole scene draw, so the engine cannot know what one is worth until it has
|
|
78
|
+
* paid for it: the node measures the draw it just took and smooths that reading, and a level whose
|
|
79
|
+
* smoothed cost is a large share of the frame period is re-rendered less often. This is automatic
|
|
80
|
+
* because the value it reacts to is a measurement, not a setting — a game sets nothing, and a
|
|
81
|
+
* cheap level is never widened and behaves exactly as before. The widened trail is capped by the
|
|
82
|
+
* window's own margin, so the camera stays inside the region that level serves and everything that
|
|
83
|
+
* level serves stays inside the map; a level with no such margin is never widened at all.
|
|
84
|
+
*
|
|
85
|
+
* `false` puts every level back on the `refreshStep` it was given, which is also what a harness
|
|
86
|
+
* that wants to count today's renders uses.
|
|
87
|
+
* `?tnAdaptiveRefresh=0` in the page URL makes the default `false` from the node's first setup.
|
|
88
|
+
*/
|
|
89
|
+
readonly adaptiveRefresh?: boolean;
|
|
90
|
+
/**
|
|
91
|
+
* Fraction of the display period a level's smoothed render cost may take before its refresh trail
|
|
92
|
+
* widens, `(0, 1]`, default 0.4.
|
|
93
|
+
*
|
|
94
|
+
* The period is the frame's own `deltaTime`, capped at the 60 fps frame (16.7 ms). The cap is what
|
|
95
|
+
* keeps the budget honest: the frame that renders an expensive level is itself long because of that
|
|
96
|
+
* render, so reading the share against its own inflated delta would count the cost twice and let
|
|
97
|
+
* the very level that needs adapting pass its own test. At 60 Hz the cap is the frame itself; on a
|
|
98
|
+
* 120 Hz panel the same render is twice the share it is at 60; below 60 the cap holds the budget
|
|
99
|
+
* at the 60 fps frame rather than growing with the stall. Below the share nothing changes at all,
|
|
100
|
+
* and above it the trail widens in proportion to the overshoot,
|
|
101
|
+
* because that is the ratio between what the level costs and what a frame can afford to spend on
|
|
102
|
+
* it — a level four times over the share refreshs about four times less often, until the cap
|
|
103
|
+
* below it runs out.
|
|
104
|
+
*/
|
|
105
|
+
readonly expensiveRefreshShare?: number;
|
|
106
|
+
/**
|
|
107
|
+
* Raise the finest level's texel size gate while its own render is too expensive for the frame, default
|
|
108
|
+
* true.
|
|
109
|
+
*
|
|
110
|
+
* The same measurement adaptive refresh reads — the smoothed cost of the level's own last render,
|
|
111
|
+
* against the share of the frame it may take — drives a second, independent adaptation: a level
|
|
112
|
+
* whose render is over budget sizes its gate up in steps of 1.5 until it is affordable again, up
|
|
113
|
+
* to 8 times the configured gate, and halves it back toward 1 once the render is comfortably under
|
|
114
|
+
* half the budget. The gate only ever judges a caster by its size (see `minCasterTexels`), so this
|
|
115
|
+
* drops the tiniest props first and never a building, and a level that is cheap is never touched:
|
|
116
|
+
* it stays at scale 1 and submits exactly what it did before.
|
|
117
|
+
*
|
|
118
|
+
* Coarse levels always stay at scale 1 so resolved casters survive the handover.
|
|
119
|
+
* `false` pins every level at scale 1, which is also what a harness that wants today's draw
|
|
120
|
+
* counts uses.
|
|
121
|
+
*/
|
|
122
|
+
readonly adaptiveCasterGate?: boolean;
|
|
123
|
+
/**
|
|
124
|
+
* How long a level waits after its own last render before an invalidation may re-render it, in
|
|
125
|
+
* seconds. One value for every level, or one per level finest first, the last entry standing in
|
|
126
|
+
* for the rest. Default `0.25 * extent / finestExtent` — 0.25 s, 1 s and 3.33 s for extents
|
|
127
|
+
* 24 / 96 / 320 — and `0` renders on the very next frame, which is what the node did before.
|
|
128
|
+
*
|
|
129
|
+
* A streamed world invalidates its shadows on every residency update, and a cell admitted at the
|
|
130
|
+
* ring edge lands in the coarsest window: the level that redraws for it is the one paying for the
|
|
131
|
+
* whole ring's wide casters, ten times a second where movement alone asks for two. A level
|
|
132
|
+
* waiting out its delay keeps the map and window it has, which is already right for every static
|
|
133
|
+
* caster in it, so only a newly streamed caster is missing — the trade is that a far tree's
|
|
134
|
+
* shadow can appear up to the delay late (3.33 s at extent 320, invisible on a level whose texel
|
|
135
|
+
* is wider than the tree). A window that moved is never delayed: that is a different reason, and
|
|
136
|
+
* it is not this option's.
|
|
137
|
+
*/
|
|
138
|
+
readonly invalidationDelay?: number | readonly number[];
|
|
139
|
+
/**
|
|
140
|
+
* How far behind the window centre each level camera sits, in world units. Default 200. An
|
|
141
|
+
* explicit `lightDistance` *and* `depthRange` switch the level's light-space depth off the derived
|
|
142
|
+
* span below and back onto this pair, so a game that knows its own world sizes can still say so.
|
|
143
|
+
*/
|
|
144
|
+
readonly lightDistance?: number;
|
|
145
|
+
/**
|
|
146
|
+
* Depth range each level camera covers past its centre, in world units. Default 400. Read only
|
|
147
|
+
* together with `lightDistance`; on its own the span is still derived.
|
|
148
|
+
*/
|
|
149
|
+
readonly depthRange?: number;
|
|
150
|
+
/**
|
|
151
|
+
* Texels of a level a caster must cover before it draws into that level, default 1.5. A level's
|
|
152
|
+
* texel is `2 * extent / mapSize`, so the finest levels keep everything and the coarse ones keep
|
|
153
|
+
* only what they can resolve: a fern is a whole number of texels in a 48 m window and a fraction
|
|
154
|
+
* of one in a 640 m window, so it stops being drawn there and the shadow it casts is the ground
|
|
155
|
+
* cover's own, not its silhouette's. Set 0 to draw every caster into every level.
|
|
156
|
+
*/
|
|
157
|
+
readonly minCasterTexels?: number;
|
|
158
|
+
/** Follow the framed receiving surface when the eye is more than one fine extent above it.
|
|
159
|
+
* Default true; false keeps eye follow for every camera. Walking cameras keep eye follow.
|
|
160
|
+
*/
|
|
161
|
+
readonly followViewFocus?: boolean;
|
|
162
|
+
/**
|
|
163
|
+
* The smallest ratio of a level's light-space height to its width, `(0, 1]`, default 1 (square levels).
|
|
164
|
+
* A low sun stretches a shadow texel along the floor by `1 / sin(elevation)`. A value under 1 shrinks
|
|
165
|
+
* the height to `sin(elevation)` times the width, never under this value, so a texel covers the same
|
|
166
|
+
* floor area at any sun height. The costs: a wall taller than a level's height is read from a wider
|
|
167
|
+
* level, a level centred on the eye holds the floor only about `eye height / tan(elevation)` from the
|
|
168
|
+
* camera, and a wide filter disc (a source angle near 0.7 degrees) crosses the level's top and bottom
|
|
169
|
+
* edge and leaves a lit patch in a thin shadow (PRD-634, sun 4 ramp), so it is an opt-in.
|
|
170
|
+
*/
|
|
171
|
+
readonly minWindowAspect?: number;
|
|
172
|
+
/** Measure receiver-plane slope across each level's texel footprint to prevent coarse acne.
|
|
173
|
+
* Default true; false preserves only the authored bias. Custom filterNode owns its footprint.
|
|
174
|
+
*/
|
|
175
|
+
readonly receiverPlaneBias?: boolean;
|
|
176
|
+
/**
|
|
177
|
+
* Draw registered AutoLOD chains with a coarser rung past the finest level, default true. A level
|
|
178
|
+
* takes the coarsest rung whose geometric error is within one of its texels, and never a rung
|
|
179
|
+
* finer than the main pass shows; where no rung is that accurate the caster keeps its geometry.
|
|
180
|
+
* Alpha-tested and transparent casters keep casting on every level that resolves their bounds;
|
|
181
|
+
* dropping their whole shadow at the fine window edge loses canopy and fences.
|
|
182
|
+
* Geometry swaps are restored before the next level, mover map and main pass.
|
|
183
|
+
*/
|
|
184
|
+
readonly shadowLodBias?: boolean;
|
|
185
|
+
/**
|
|
186
|
+
* The most error, in texels of a level, that a coarser rung may have on that level, default 1.
|
|
187
|
+
* A rung within a texel is as good as the full mesh at that resolution; a larger budget draws
|
|
188
|
+
* fewer triangles and shows facets on a shadow's edge, and `Infinity` draws the coarsest rung on
|
|
189
|
+
* every level past the finest. Read only with `shadowLodBias`.
|
|
190
|
+
*/
|
|
191
|
+
readonly shadowLodTexels?: number;
|
|
192
|
+
/**
|
|
193
|
+
* Redraw only the pages an invalidation dirtied, default true. A level whose window did not move
|
|
194
|
+
* and whose asks named under half its pages renders those rectangles alone: pages casters were
|
|
195
|
+
* removed from are put back to the far plane first, pages casters streamed into are just drawn.
|
|
196
|
+
* `false` renders the whole level for every invalidation, as before. A VSM shadow map always
|
|
197
|
+
* renders whole, because its blur pass reads the entire map.
|
|
198
|
+
*/
|
|
199
|
+
readonly partialRedraw?: boolean;
|
|
200
|
+
/**
|
|
201
|
+
* Quiet frames an automatically detected mover must exceed before it goes back into the cached
|
|
202
|
+
* levels, default 100 (Unreal's `FramesStaticThreshold`: it settles on quiet frame 101). A caster whose world matrix, instance matrix or
|
|
203
|
+
* deformation changed is drawn through the mover maps without a `trackCaster` call; this is how
|
|
204
|
+
* long it must hold still before its shadow is baked into the cache again. Positive integer.
|
|
205
|
+
*/
|
|
206
|
+
readonly staticAfterFrames?: number;
|
|
207
|
+
/** Print the `TN_VIRTUAL_SHADOW` line every `markerEvery` frames; `false` silences it. Default 300. */
|
|
208
|
+
readonly marker?: boolean | number;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/** Per-frame counters, readable any time through {@link VirtualShadowNode.stats}. */
|
|
212
|
+
export interface IVirtualShadowStats {
|
|
213
|
+
readonly frame: number;
|
|
214
|
+
readonly levels: number;
|
|
215
|
+
/** Levels whose window moved this frame and were re-rendered. */
|
|
216
|
+
readonly moved: number;
|
|
217
|
+
/** Levels re-rendered because `invalidateAll()` or explicit tracker invalidation asked for it. */
|
|
218
|
+
readonly invalidated: number;
|
|
219
|
+
/** Tracked casters, as of this frame. */
|
|
220
|
+
readonly movers: number;
|
|
221
|
+
/**
|
|
222
|
+
* Casters the node classified as movers by measuring them, as of this frame: a world or instance
|
|
223
|
+
* matrix that changed, or a deforming mesh. Counted apart from {@link movers}, which is `trackCaster`.
|
|
224
|
+
*/
|
|
225
|
+
readonly autoMovers: number;
|
|
226
|
+
/**
|
|
227
|
+
* Static-to-mover and mover-to-static changes of those casters over the node's lifetime. Each one
|
|
228
|
+
* asks the levels for one region redraw, never a full one.
|
|
229
|
+
*/
|
|
230
|
+
readonly autoTransitions: number;
|
|
231
|
+
/**
|
|
232
|
+
* Mean JS time of the classification scan per frame, in milliseconds, over the node's lifetime.
|
|
233
|
+
* It is the number the scan's 0.05 ms budget is judged against.
|
|
234
|
+
*/
|
|
235
|
+
readonly autoScanMs: number;
|
|
236
|
+
/** Mover maps rendered this frame: one per level when at least one caster is tracked. */
|
|
237
|
+
readonly moverRenders: number;
|
|
238
|
+
/** Levels served from their cached map this frame. */
|
|
239
|
+
readonly cached: number;
|
|
240
|
+
/** Levels rendered this frame, for any reason. */
|
|
241
|
+
readonly rendered: number;
|
|
242
|
+
/**
|
|
243
|
+
* Levels that wanted a render this frame and did not get one, because the node renders at most
|
|
244
|
+
* one level per frame. They keep the map they already have and come due again next frame.
|
|
245
|
+
*/
|
|
246
|
+
readonly deferred: number;
|
|
247
|
+
/**
|
|
248
|
+
* Levels holding a redraw for an invalidation that is still inside its own `invalidationDelay`,
|
|
249
|
+
* so this frame is not the frame they render on. They keep the map they have, which is right for
|
|
250
|
+
* every static caster in it: only a caster streamed in since is missing, and the cumulative
|
|
251
|
+
* `coalesced` below is what is being waited out.
|
|
252
|
+
*/
|
|
253
|
+
readonly held: number;
|
|
254
|
+
/** Fraction of levels served from cache over the node's lifetime. */
|
|
255
|
+
readonly reuseRatio: number;
|
|
256
|
+
/**
|
|
257
|
+
* Level renders over the node's lifetime, for any reason. `byMove` and `byInvalidation` are the two
|
|
258
|
+
* the node has — a window that moved, and an invalidation that asked and waited out its delay — and
|
|
259
|
+
* they add up to this exactly, because a render the single per-frame budget defers is counted
|
|
260
|
+
* against the reason that queued it and not again when it is finally taken.
|
|
261
|
+
*/
|
|
262
|
+
readonly rendersTotal: number;
|
|
263
|
+
/** Of those, the renders taken because a level's window moved. */
|
|
264
|
+
readonly byMove: number;
|
|
265
|
+
/**
|
|
266
|
+
* Pages every level's window travelled between its renders, over the node's lifetime: the sum of
|
|
267
|
+
* `|ΔminX| + |ΔminY|` at each render. Unlike `byMove` it does not depend on how many frames sampled
|
|
268
|
+
* the path, so two runs of one route at different frame rates report the same number.
|
|
269
|
+
*/
|
|
270
|
+
readonly windowSteps: number;
|
|
271
|
+
/** Of those, the renders taken because an invalidation asked and its level's delay had passed. */
|
|
272
|
+
readonly byInvalidation: number;
|
|
273
|
+
/** Of the renders taken for an invalidation (`byInvalidation`), those whose dirty set held only streamed-in casters. */
|
|
274
|
+
readonly byAdmission: number;
|
|
275
|
+
/** Of the renders taken for an invalidation, those whose dirty set held anything else: a removed caster, a region-less ask, a caster flag change. */
|
|
276
|
+
readonly byEviction: number;
|
|
277
|
+
/** Pages the dirty set held at each render, summed over the node's lifetime. A window move counts the whole level. */
|
|
278
|
+
readonly pagesDirty: number;
|
|
279
|
+
/** Pages each render actually drew, summed over the node's lifetime. Equals pagesDirty once a partial redraw exists. */
|
|
280
|
+
readonly pagesRedrawn: number;
|
|
281
|
+
/**
|
|
282
|
+
* Invalidation asks that cost no render of their own, over the node's lifetime: absorbed by a
|
|
283
|
+
* render the level was taking anyway for its window, or merged into an ask already waiting out
|
|
284
|
+
* that level's delay. The two of these are the shape of the win — with the default delays a walk
|
|
285
|
+
* asks once a second and renders about that often, and every ask in between is counted here.
|
|
286
|
+
*/
|
|
287
|
+
readonly coalesced: number;
|
|
288
|
+
/**
|
|
289
|
+
* The same four counters per level, finest first: which window moved, which invalidation asked
|
|
290
|
+
* for a redraw, which level took the frame's single render, and which wanted one and did not get
|
|
291
|
+
* it. One entry per level per frame, so a harness reading this — or the `TN_VIRTUAL_SHADOW`
|
|
292
|
+
* marker line, which carries it — can see which level a walk keeps re-rendering instead of only
|
|
293
|
+
* how many.
|
|
294
|
+
*/
|
|
295
|
+
readonly perLevel: readonly IVirtualShadowLevelStat[];
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
/** One level's row of {@link IVirtualShadowStats}: 1 or 0 per counter, per frame. */
|
|
299
|
+
export interface IVirtualShadowLevelStat {
|
|
300
|
+
/** The level's clip extent, in world units. */
|
|
301
|
+
readonly extent: number;
|
|
302
|
+
readonly deferred: number;
|
|
303
|
+
readonly invalidated: number;
|
|
304
|
+
readonly moved: number;
|
|
305
|
+
readonly rendered: number;
|
|
306
|
+
/** Caster meshes this level's chosen camera layers submit this frame. Zero if it did not render. */
|
|
307
|
+
readonly draws: number;
|
|
308
|
+
/** The same bill split by kind; the five parts sum to {@link draws}. */
|
|
309
|
+
readonly drawsBy: IVirtualShadowDraws;
|
|
310
|
+
/** The adaptive caster gate's scale on this level, 1 when it is not shedding casters. */
|
|
311
|
+
readonly gateScale: number;
|
|
312
|
+
/** Casters the gate hid on the render this level took this frame; zero if it did not render. */
|
|
313
|
+
readonly gateHidden: number;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/** One level's caster draws, by the kind of mesh that submitted them. */
|
|
317
|
+
export interface IVirtualShadowDraws {
|
|
318
|
+
/** Caster batch meshes on the cluster layer, when the cluster half is the level's choice. */
|
|
319
|
+
readonly cluster: number;
|
|
320
|
+
/** Key-wide caster meshes on the wide layer, when the wide half is the level's choice. */
|
|
321
|
+
readonly wide: number;
|
|
322
|
+
/** Small casters, submitted by the finest level and by any level rendering a prewarm. */
|
|
323
|
+
readonly small: number;
|
|
324
|
+
/** Merged per-chunk shadow proxies (`<name>-shadow`), drawn with either caster half. */
|
|
325
|
+
readonly chunkProxy: number;
|
|
326
|
+
/** Everything else casting from layer 0 — terrain, props — which every level draws. */
|
|
327
|
+
readonly layer0: number;
|
|
328
|
+
/**
|
|
329
|
+
* GPU-scene keys: one mesh per `asset:level:part` drawn from the level's own twin of the dispatch's
|
|
330
|
+
* output, which is the whole of what a keyed map submits of the world. Zero unless a provider
|
|
331
|
+
* registered and `?tnShadowGpuKeys=1` asked, and then it replaces {@link cluster} and {@link wide}
|
|
332
|
+
* rather than adding to them: the keys draw the placements those two would have.
|
|
333
|
+
*/
|
|
334
|
+
readonly keys: number;
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
/** The mutable tally `#probe` fills; the public row only ever reads it. */
|
|
338
|
+
export interface IVirtualShadowDrawTally {
|
|
339
|
+
cluster: number;
|
|
340
|
+
wide: number;
|
|
341
|
+
small: number;
|
|
342
|
+
chunkProxy: number;
|
|
343
|
+
layer0: number;
|
|
344
|
+
keys: number;
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
/** Square levels. A fit to the ground (`0.25`, a 14.5 degree sun is where it ends) is the named override. */
|
|
348
|
+
export const DEFAULT_MIN_WINDOW_ASPECT = 1;
|
|
349
|
+
export const DEFAULT_MARKER_EVERY = 300;
|
|
350
|
+
/**
|
|
351
|
+
* The invalidation delay of the *finest* level, in seconds; every other level's is this times its
|
|
352
|
+
* extent over the finest one. A burst of streamed invalidations is paid as one render, and the
|
|
353
|
+
* level that pays it is the one whose window is widest.
|
|
354
|
+
*/
|
|
355
|
+
export const BASE_INVALIDATION_DELAY = 0.25;
|
|
356
|
+
export const DEFAULT_MIN_CASTER_TEXELS = 1.5;
|
|
357
|
+
/** Unreal's `r.Shadow.Virtual.Cache.FramesStaticThreshold`: quiet frames before a mover is static. */
|
|
358
|
+
export const DEFAULT_STATIC_AFTER_FRAMES = 100;
|
|
359
|
+
/**
|
|
360
|
+
* The share of the display period a level's render may cost before adaptive refresh widens its
|
|
361
|
+
* trail: two frames in five, 6.7 ms of a 60 Hz frame. A draw that big is worth a whole frame of its
|
|
362
|
+
* own, and a share rather than a millisecond count is what makes the same number mean the same thing
|
|
363
|
+
* on a 120 Hz panel.
|
|
364
|
+
*/
|
|
365
|
+
export const DEFAULT_EXPENSIVE_REFRESH_SHARE = 0.4;
|
|
366
|
+
|
|
367
|
+
/** The per-level entry of a scalar-or-array option, the last entry standing in for the rest. */
|
|
368
|
+
export function at(values: readonly number[], level: number): number {
|
|
369
|
+
return values[Math.min(level, values.length - 1)] as number;
|
|
370
|
+
}
|
|
@@ -806,6 +806,11 @@ export class ShadowInvalidationTracker {
|
|
|
806
806
|
this.clipmap = clipmap;
|
|
807
807
|
}
|
|
808
808
|
|
|
809
|
+
/** Dirty page keys not yet consumed by the next shadow render. */
|
|
810
|
+
get pending(): number {
|
|
811
|
+
return this.#invalidated.size;
|
|
812
|
+
}
|
|
813
|
+
|
|
809
814
|
get trackedCount(): number {
|
|
810
815
|
return this.#tracked.size;
|
|
811
816
|
}
|
|
@@ -129,10 +129,23 @@ export function installPartialRender(
|
|
|
129
129
|
current: () => IPartialPass | undefined,
|
|
130
130
|
): void {
|
|
131
131
|
const stock = node.renderShadow.bind(node);
|
|
132
|
+
let quadBuilt = false;
|
|
132
133
|
node.renderShadow = (frame) => {
|
|
133
134
|
const pass = current();
|
|
134
135
|
const pixels = pass?.pixels;
|
|
135
136
|
if (pass === undefined || pixels === undefined) {
|
|
137
|
+
// The reset quad's pipeline is built on its first draw. Drawn once here, under the whole
|
|
138
|
+
// map's own clear, it is built with the first shadow render, behind a loading curtain, not on
|
|
139
|
+
// the first partial reset that a camera turn in play triggers (PRD-790).
|
|
140
|
+
if (!quadBuilt && frame.renderer !== null) {
|
|
141
|
+
quadBuilt = true;
|
|
142
|
+
const { scene, camera, object, material } = frame;
|
|
143
|
+
resetDepth(frame.renderer, node.shadow.camera.reversedDepth === true);
|
|
144
|
+
frame.scene = scene;
|
|
145
|
+
frame.camera = camera;
|
|
146
|
+
frame.object = object;
|
|
147
|
+
frame.material = material;
|
|
148
|
+
}
|
|
136
149
|
stock(frame);
|
|
137
150
|
return;
|
|
138
151
|
}
|