@threenative/core 0.3.4 → 0.3.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/capabilities.json +1505 -79
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-CljaDv4D.d.ts → game-Jz4Fdoeb.d.ts} +114 -11
- package/dist/hot.d.ts +4 -4
- package/dist/index.d.ts +712 -118
- package/dist/index.js +12437 -4955
- package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
- package/dist/playtest.d.ts +6 -10
- package/dist/playtest.js +57 -24
- package/dist/react-css.d.ts +62 -0
- package/dist/react-css.js +591 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +766 -73
- package/dist/world.js +9307 -3543
- package/gpl/recipes/export_world.py +18 -1
- package/mcp/blender-server.mjs +7 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +2 -2
- package/mcp/servers.mjs +4 -4
- package/package.json +15 -9
- package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
- package/patches/three@0.185.1.patch +6594 -700
- package/scripts/apply-three-patch.mjs +62 -4
- package/src/animation-blend.ts +264 -0
- package/src/animation-composition.ts +362 -0
- package/src/animation-layers.ts +260 -0
- package/src/animation-root-motion.ts +283 -0
- package/src/animation.ts +896 -0
- package/src/assets.ts +1303 -0
- package/src/atmosphere/index.ts +335 -0
- package/src/atmosphere/luts.ts +298 -0
- package/src/atmosphere/params.ts +323 -0
- package/src/audio.ts +912 -0
- package/src/billboard.ts +124 -0
- package/src/bone-lengths.ts +157 -0
- package/src/camera-shake.ts +116 -0
- package/src/canvas-layer.ts +47 -0
- package/src/clip-audit.ts +401 -0
- package/src/clustered-batch.ts +492 -0
- package/src/clustered-mesh.ts +638 -0
- package/src/compute-driven.ts +176 -0
- package/src/compute-timing.ts +318 -0
- package/src/config.ts +593 -0
- package/src/debug.ts +82 -0
- package/src/engine-render-hook.ts +25 -0
- package/src/entities.ts +79 -0
- package/src/entity-snapshot.ts +53 -0
- package/src/flight.ts +683 -0
- package/src/fluid-field.ts +748 -0
- package/src/fluid-particles.ts +1253 -0
- package/src/frame-budget.ts +1368 -0
- package/src/game.ts +2408 -0
- package/src/geometry-capture.ts +1098 -0
- package/src/gpu-class.ts +160 -0
- package/src/gpu-frame-observation.ts +424 -0
- package/src/gpu-readback.ts +143 -0
- package/src/gpu-scene-bvh.ts +464 -0
- package/src/grounding.ts +100 -0
- package/src/hot.ts +161 -0
- package/src/import-meta.d.ts +13 -0
- package/src/index.ts +1536 -0
- package/src/input.ts +690 -0
- package/src/instanced-batch-lod.ts +283 -0
- package/src/instanced-batch.ts +274 -0
- package/src/interpolation.ts +129 -0
- package/src/launch-diagnostics.ts +161 -0
- package/src/loop.ts +574 -0
- package/src/matrix-world.ts +245 -0
- package/src/merge-parts.ts +812 -0
- package/src/model-lod.ts +1315 -0
- package/src/net-protocol.ts +333 -0
- package/src/net-session.ts +477 -0
- package/src/net.ts +80 -0
- package/src/ocean/fft.ts +72 -0
- package/src/ocean/spectral.ts +728 -0
- package/src/particle-significance.ts +102 -0
- package/src/particles.ts +648 -0
- package/src/path-follow.ts +175 -0
- package/src/picking.ts +250 -0
- package/src/pipeline-census.ts +1566 -0
- package/src/platform.ts +210 -0
- package/src/playtest.ts +850 -0
- package/src/pointer-events.ts +411 -0
- package/src/pose-measure.ts +435 -0
- package/src/profiling/FrameCounters.ts +231 -0
- package/src/profiling/Spans.ts +548 -0
- package/src/profiling/opacity-convention.ts +21 -0
- package/src/profiling/render-list-validate.ts +175 -0
- package/src/profiling/render-trap-audit.ts +84 -0
- package/src/profiling/scene-warning.ts +190 -0
- package/src/profiling/span-probes.ts +191 -0
- package/src/profiling/unlit-foliage-warning.ts +149 -0
- package/src/projection-apply.ts +1529 -0
- package/src/projection-marker.ts +142 -0
- package/src/projection-plan.ts +1258 -0
- package/src/projection-skinned.ts +419 -0
- package/src/projection-stability.ts +409 -0
- package/src/projection-uniform.ts +328 -0
- package/src/random.ts +41 -0
- package/src/react-css.ts +604 -0
- package/src/react-glyphs.ts +114 -0
- package/src/react-host.ts +576 -0
- package/src/react-layout.ts +265 -0
- package/src/react.ts +60 -0
- package/src/render/alpha-antialiasing.ts +159 -0
- package/src/render/batched-velocity.ts +126 -0
- package/src/render/chain.ts +1021 -0
- package/src/render/daylight.ts +189 -0
- package/src/render/depth-pyramid.ts +596 -0
- package/src/render/foliage-alpha.ts +166 -0
- package/src/render/material-key.ts +60 -0
- package/src/render/mesh-pool.ts +144 -0
- package/src/render/probe-volume.ts +1668 -0
- package/src/render/resolution-subrect.ts +253 -0
- package/src/render/velocity.ts +442 -0
- package/src/render/virtual-shadow-pages.ts +827 -0
- package/src/render/virtual-shadow-partial.ts +174 -0
- package/src/render/virtual-shadow.ts +3330 -0
- package/src/render/world-impostor-surface.ts +722 -0
- package/src/render/world-impostor.ts +558 -0
- package/src/render-camera-cull.ts +441 -0
- package/src/render-pass-budget.ts +501 -0
- package/src/renderProjection.ts +758 -0
- package/src/renderer-config.ts +127 -0
- package/src/renderer.ts +1847 -0
- package/src/replay-protocol.ts +85 -0
- package/src/replay.ts +205 -0
- package/src/resolution-scaler.ts +819 -0
- package/src/rig-preparation.ts +271 -0
- package/src/ripple-field.ts +432 -0
- package/src/scale.ts +109 -0
- package/src/scene.ts +239 -0
- package/src/schedule.ts +155 -0
- package/src/skeletal-mesh.ts +61 -0
- package/src/skeleton.ts +100 -0
- package/src/snow-field.ts +744 -0
- package/src/softbody-topology.ts +269 -0
- package/src/softbody.ts +516 -0
- package/src/sprite-animator.ts +222 -0
- package/src/startup-readiness.ts +386 -0
- package/src/state.ts +66 -0
- package/src/static-transform.ts +274 -0
- package/src/storage-buffer.ts +253 -0
- package/src/streaming.ts +308 -0
- package/src/target-fps.ts +92 -0
- package/src/terrain-jobs-worker.ts +17 -0
- package/src/terrain-jobs.ts +353 -0
- package/src/textures.ts +39 -0
- package/src/tracers.ts +237 -0
- package/src/ui-bridge.ts +368 -0
- package/src/ui-hit-regions.ts +380 -0
- package/src/ui-layer.ts +83 -0
- package/src/ui-state.ts +220 -0
- package/src/version.ts +2 -0
- package/src/viewport.ts +253 -0
- package/src/warmup.ts +1357 -0
- package/src/water-surface.ts +384 -0
- package/src/wave-field.ts +524 -0
- package/src/world-capabilities.ts +131 -0
- package/src/world-cell-proxy.ts +392 -0
- package/src/world-cells.ts +10564 -0
- package/src/world-gpu-scene.ts +3354 -0
- package/src/world-heightmap.ts +82 -0
- package/src/world-package.ts +469 -0
- package/src/world-passes.ts +582 -0
- package/src/world-region.ts +17 -0
- package/src/world-terrain-splat.ts +564 -0
- package/src/world-tiles.ts +3826 -0
- package/src/world-topology.ts +370 -0
- package/src/world-validate.ts +48 -0
- package/src/world.ts +805 -0
|
@@ -0,0 +1,1529 @@
|
|
|
1
|
+
import {
|
|
2
|
+
BatchedMesh,
|
|
3
|
+
type BufferGeometry,
|
|
4
|
+
type Color,
|
|
5
|
+
InstancedMesh,
|
|
6
|
+
LOD,
|
|
7
|
+
type Light,
|
|
8
|
+
Line,
|
|
9
|
+
LineLoop,
|
|
10
|
+
LineSegments,
|
|
11
|
+
type Material,
|
|
12
|
+
Matrix4,
|
|
13
|
+
Mesh,
|
|
14
|
+
type Object3D,
|
|
15
|
+
type PointLight,
|
|
16
|
+
Points,
|
|
17
|
+
Scene,
|
|
18
|
+
SkinnedMesh,
|
|
19
|
+
type SpotLight,
|
|
20
|
+
Sprite,
|
|
21
|
+
type SpriteMaterial,
|
|
22
|
+
} from "three";
|
|
23
|
+
|
|
24
|
+
import type { IGeometryOwnership } from "./geometry-capture.js";
|
|
25
|
+
import { MIN_BATCH_MEMBERS, isLight } from "./projection-plan.js";
|
|
26
|
+
import type {
|
|
27
|
+
IProjectionBatchGroup,
|
|
28
|
+
IProjectionExactEntry,
|
|
29
|
+
IProjectionMaterialGroup,
|
|
30
|
+
IProjectionProjectPlan,
|
|
31
|
+
IProjectionUniformGroup,
|
|
32
|
+
} from "./projection-plan.js";
|
|
33
|
+
import { SkinnedBatch, isSimilarityTransform } from "./projection-skinned.js";
|
|
34
|
+
import { baseColorOf, uniformUnchanged } from "./projection-uniform.js";
|
|
35
|
+
import {
|
|
36
|
+
disposeBatchedMeshVelocity,
|
|
37
|
+
ensureBatchedMeshVelocity,
|
|
38
|
+
isBatchedMeshVelocityPatched,
|
|
39
|
+
setBatchedMeshMatrixWithVelocity,
|
|
40
|
+
setBatchedMeshPreviousMatrix,
|
|
41
|
+
} from "./render/batched-velocity.js";
|
|
42
|
+
import type { ProjectionExactReason, ProjectionMaterialChecks } from "./renderProjection.js";
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* The apply-and-restore seam of the render projection (P2-3).
|
|
46
|
+
*
|
|
47
|
+
* Everything here mutates: batches are created and disposed, instance slots are handed out and
|
|
48
|
+
* recycled, stand-ins are built and dropped, lights are mirrored, and every source that left the
|
|
49
|
+
* authored scene is retired. The decision of what to do arrived as an immutable plan from
|
|
50
|
+
* `projection-plan.ts`; this module owns all of the state that doing it requires, and all of the
|
|
51
|
+
* restoration paths that undo it. Restoration is not optional bookkeeping — a slot that is not
|
|
52
|
+
* collapsed, a proxy that is not removed, or a light that outlives its source each draw something
|
|
53
|
+
* the game did not author.
|
|
54
|
+
*/
|
|
55
|
+
|
|
56
|
+
/** A transform with no volume. Every triangle drawn through it is degenerate and discarded. */
|
|
57
|
+
const ZERO_MATRIX = /* @__PURE__ */ new Matrix4().multiplyScalar(0);
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* The material a uniform batch draws with: the group's representative with its base colour removed.
|
|
61
|
+
*
|
|
62
|
+
* `Color.setHex` converts sRGB into the working colour space as it decodes, so the components on the
|
|
63
|
+
* material are already linear. The instance colours are read from the same place and the node
|
|
64
|
+
* material multiplies the two, so leaving the shared colour at the identity leaves the drawn colour
|
|
65
|
+
* as the source colour, bit for bit, rather than a colour converted twice. Nothing here chooses a
|
|
66
|
+
* colour: it takes the game's own and removes the one value the draw now carries per instance.
|
|
67
|
+
*/
|
|
68
|
+
function whiteClone(source: Material): Material {
|
|
69
|
+
const clone = source.clone() as Material & { color?: Color };
|
|
70
|
+
clone.color?.setRGB(1, 1, 1);
|
|
71
|
+
return clone;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Headroom on every batch, so the common case of a game adding a few more props does not rebuild
|
|
76
|
+
* one. A batch that overflows anyway is rebuilt at its new size rather than dropping the object.
|
|
77
|
+
*/
|
|
78
|
+
const BATCH_GROWTH = 1.5;
|
|
79
|
+
const BATCH_MIN_SLOTS = 16;
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* WebGPU's guaranteed minimum `maxStorageBufferBindingSize`. A skinned palette never binds more,
|
|
83
|
+
* so no device is asked for a limit it may not grant; rigs past it keep their own draw.
|
|
84
|
+
*/
|
|
85
|
+
const PALETTE_BINDING_BYTES = 134_217_728;
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* PRD-238 measurement (2026-08-28, tn-web on NVIDIA/Turing, 3 paired runs, frames 226–899): the
|
|
89
|
+
* 4,096-member rung with 75% outside the frustum reported 4,097 → 1,025 scene draw submissions
|
|
90
|
+
* (culling off → on; the harness excludes one presentation draw) and render.p50 1.60 → 1.10 ms
|
|
91
|
+
* (median of the three p50s, −0.50 ms). Keep culling enabled; the verification record is
|
|
92
|
+
* `docs/verification/runtime-perf-state.md` under PRD-238.
|
|
93
|
+
*/
|
|
94
|
+
const PER_OBJECT_FRUSTUM_CULLED = true;
|
|
95
|
+
const SORT_BATCH_OBJECTS = false;
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* How many uniform-batch members the drift sweep may examine in one frame (PRD-462).
|
|
99
|
+
*
|
|
100
|
+
* The check is what makes the colour lane's per-frame sync ten times the shared lane's: one
|
|
101
|
+
* `Object.values` and one compare per member per frame, measured at 1,126 ns a member, which is
|
|
102
|
+
* 4.61 ms of a 4,096-material frame's 7.5 ms reconcile. Most of those frames are proving that
|
|
103
|
+
* nothing moved, and a game that animates a material's roughness does so on a handful of frames,
|
|
104
|
+
* not on all of them. So the sweep visits this many member positions a frame and carries its
|
|
105
|
+
* cursor across frames: every material is proved within `ceil(members / this)` frames, and the
|
|
106
|
+
* worst case at L4@4,096 is 8 — reported as `materialCheckStaleFrames`, never assumed.
|
|
107
|
+
*
|
|
108
|
+
* 512 is measured, not round: it takes the check from 4.61 ms to ~0.58 ms a frame, which puts
|
|
109
|
+
* L4@4,096's reconcile (3.5 ms) clearly under Godot's 5.95 ms for the same rung, and a smaller
|
|
110
|
+
* budget buys nothing a game can see while lengthening the staleness every frame pays for.
|
|
111
|
+
*/
|
|
112
|
+
const MATERIAL_CHECKS_PER_FRAME = 512;
|
|
113
|
+
|
|
114
|
+
interface IBatch {
|
|
115
|
+
readonly mesh: InstancedMesh;
|
|
116
|
+
readonly group: IProjectionBatchGroup;
|
|
117
|
+
readonly geometry: BufferGeometry;
|
|
118
|
+
readonly material: Material;
|
|
119
|
+
/**
|
|
120
|
+
* True when the members' materials differ only in base colour: `material` is then a clone this
|
|
121
|
+
* mirror owns, and the colour each member draws with lives in the batch's instance colours.
|
|
122
|
+
*/
|
|
123
|
+
readonly uniform: boolean;
|
|
124
|
+
/** Source object per instance slot, so a released slot can be reused rather than leaked. */
|
|
125
|
+
readonly instances: Map<Object3D, number>;
|
|
126
|
+
readonly free: number[];
|
|
127
|
+
/** Slots handed out so far, which is also where the next unused one begins. */
|
|
128
|
+
used: number;
|
|
129
|
+
capacity: number;
|
|
130
|
+
/** Whether an instance matrix was written this frame, so the upload is flagged once per batch. */
|
|
131
|
+
dirty: boolean;
|
|
132
|
+
/** Whether an instance colour was written this frame, flagged once per batch for the same reason. */
|
|
133
|
+
colorsDirty: boolean;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* The material-keyed batch: many distinct geometries packed under one material.
|
|
138
|
+
*
|
|
139
|
+
* Unlike `IBatch` this owns copies of vertex data — that is what lets it fold geometries the
|
|
140
|
+
* instanced lane cannot — and so it carries the obligations a copy brings: budgets sized from the
|
|
141
|
+
* whole group before anything is built, a rebuild whenever the group's geometry set changes
|
|
142
|
+
* (`builtRevision` against the group's), and the scan's stream watch demoting any geometry whose
|
|
143
|
+
* versions move after admission. Slots are instance ids exactly as on the instanced lane: hidden
|
|
144
|
+
* rather than deleted when released, so the free list recycles them without touching the batch.
|
|
145
|
+
*/
|
|
146
|
+
interface IBatched {
|
|
147
|
+
readonly mesh: BatchedMesh;
|
|
148
|
+
readonly group: IProjectionMaterialGroup;
|
|
149
|
+
readonly material: Material;
|
|
150
|
+
/** Source geometry to its packed sub-geometry id. */
|
|
151
|
+
readonly geometries: Map<BufferGeometry, number>;
|
|
152
|
+
/** Source object per instance slot, so a released slot can be reused rather than leaked. */
|
|
153
|
+
readonly instances: Map<Object3D, number>;
|
|
154
|
+
readonly free: number[];
|
|
155
|
+
/** Instance ids handed out so far, which is also where the next unused one begins. */
|
|
156
|
+
used: number;
|
|
157
|
+
capacity: number;
|
|
158
|
+
builtRevision: number;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/** What the mirror last knew about a source, so an unchanged source costs a compare and no work. */
|
|
162
|
+
interface ISourceState {
|
|
163
|
+
readonly matrixWorld: Matrix4;
|
|
164
|
+
visible: boolean;
|
|
165
|
+
geometry: BufferGeometry | undefined;
|
|
166
|
+
material: Material | Material[] | undefined;
|
|
167
|
+
/** The batch this source is an instance of, so a lane change releases the old slot directly. */
|
|
168
|
+
batch: IBatch | IBatched | SkinnedBatch;
|
|
169
|
+
/**
|
|
170
|
+
* The instance colour last written for this source, as three components. `NaN` on a fresh slot so
|
|
171
|
+
* the first write always happens — a colour that is genuinely `NaN` is not a colour three draws.
|
|
172
|
+
*/
|
|
173
|
+
red: number;
|
|
174
|
+
green: number;
|
|
175
|
+
blue: number;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
function exactObject(entry: IProjectionExactEntry): Object3D {
|
|
179
|
+
if (entry.object === undefined)
|
|
180
|
+
throw new Error("Projection exact entry was cleared before apply.");
|
|
181
|
+
return entry.object;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/**
|
|
185
|
+
* A stand-in of the same class as its source, with none of its children.
|
|
186
|
+
*
|
|
187
|
+
* Constructed through the source's own constructor so an unusual `Mesh` subclass keeps whatever
|
|
188
|
+
* its class does at draw time, rather than being flattened into a plain `Mesh` that merely looks
|
|
189
|
+
* like it.
|
|
190
|
+
*/
|
|
191
|
+
function shallowProxy(object: Object3D): Object3D {
|
|
192
|
+
const source = object as Mesh & {
|
|
193
|
+
isInstancedMesh?: boolean;
|
|
194
|
+
isSkinnedMesh?: boolean;
|
|
195
|
+
isSprite?: boolean;
|
|
196
|
+
isPoints?: boolean;
|
|
197
|
+
isLine?: boolean;
|
|
198
|
+
isLineSegments?: boolean;
|
|
199
|
+
isLineLoop?: boolean;
|
|
200
|
+
isLOD?: boolean;
|
|
201
|
+
count?: number;
|
|
202
|
+
};
|
|
203
|
+
// Constructed by class, not by calling the source's constructor with no arguments.
|
|
204
|
+
//
|
|
205
|
+
// Calling it with none does not fail loudly, which is the problem. `new InstancedMesh()` builds
|
|
206
|
+
// happily with `count` undefined and a zero-length instance buffer — a stand-in that is an
|
|
207
|
+
// `InstancedMesh` by every type check and draws nothing. Nothing throws, nothing warns, and the
|
|
208
|
+
// instances are simply gone: the same shape of defect as the merge that dropped two of three
|
|
209
|
+
// instances, arrived at by a different route. What actually keeps them is
|
|
210
|
+
// `copySpecializedState` below; naming each class here is what makes the stand-in the right size
|
|
211
|
+
// to begin with rather than relying on that repair.
|
|
212
|
+
if (source.isInstancedMesh === true) {
|
|
213
|
+
return new InstancedMesh(source.geometry, source.material as Material, source.count ?? 1);
|
|
214
|
+
}
|
|
215
|
+
if (source.isSkinnedMesh === true) return new SkinnedMesh(source.geometry, source.material);
|
|
216
|
+
if (source.isSprite === true) return new Sprite(source.material as SpriteMaterial);
|
|
217
|
+
if (source.isPoints === true) return new Points(source.geometry, source.material);
|
|
218
|
+
// `LineSegments` and `LineLoop` both set `isLine`, so the flag alone would flatten either into
|
|
219
|
+
// a plain `Line` and draw its separate segments joined end to end.
|
|
220
|
+
if (source.isLineSegments === true) return new LineSegments(source.geometry, source.material);
|
|
221
|
+
if (source.isLineLoop === true) return new LineLoop(source.geometry, source.material);
|
|
222
|
+
if (source.isLine === true) return new Line(source.geometry, source.material);
|
|
223
|
+
if (source.isLOD === true) return new LOD();
|
|
224
|
+
return new Mesh(source.geometry, source.material);
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/**
|
|
228
|
+
* Copies the state that makes a specialized mesh the thing it is.
|
|
229
|
+
*
|
|
230
|
+
* Shared by reference wherever three.js allows it, so the game animating a skeleton or writing an
|
|
231
|
+
* instance matrix drives what actually draws rather than a copy that stopped tracking it.
|
|
232
|
+
*/
|
|
233
|
+
function copySpecializedState(source: Object3D, target: Object3D): void {
|
|
234
|
+
const from = source as SkinnedMesh & InstancedMesh & Mesh;
|
|
235
|
+
const to = target as SkinnedMesh & InstancedMesh & Mesh;
|
|
236
|
+
if ((from as { isInstancedMesh?: boolean }).isInstancedMesh === true) {
|
|
237
|
+
to.count = from.count;
|
|
238
|
+
to.instanceMatrix = from.instanceMatrix;
|
|
239
|
+
to.instanceColor = from.instanceColor;
|
|
240
|
+
}
|
|
241
|
+
if ((from as { isSkinnedMesh?: boolean }).isSkinnedMesh === true) {
|
|
242
|
+
// The game's own skeleton, so the bones it animates are the bones that deform this draw.
|
|
243
|
+
to.skeleton = from.skeleton;
|
|
244
|
+
to.bindMatrix = from.bindMatrix;
|
|
245
|
+
to.bindMatrixInverse = from.bindMatrixInverse;
|
|
246
|
+
to.bindMode = from.bindMode;
|
|
247
|
+
}
|
|
248
|
+
// Shared, not copied: a game writing `influences[0] = t` every frame writes into this array.
|
|
249
|
+
to.morphTargetInfluences = from.morphTargetInfluences;
|
|
250
|
+
to.morphTargetDictionary = from.morphTargetDictionary;
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/**
|
|
254
|
+
* The mirror itself: the private scene the renderer is handed while the projection holds, plus
|
|
255
|
+
* every batch, slot table, stand-in and mirrored light behind it.
|
|
256
|
+
*
|
|
257
|
+
* Constructed and driven only by `SceneRenderProjection`, which keeps the public API, the report
|
|
258
|
+
* assembly and the deoptimization verdict; everything that touches renderer-owned state lives
|
|
259
|
+
* here, so the mutation boundary is one class and restoration has exactly one owner.
|
|
260
|
+
*/
|
|
261
|
+
export class ProjectionMirror {
|
|
262
|
+
/** Handed to the renderer whenever the projection is faithful. Never shown to the game. */
|
|
263
|
+
readonly scene = new Scene();
|
|
264
|
+
readonly #batches = new Map<IProjectionBatchGroup, IBatch>();
|
|
265
|
+
readonly #materialBatches = new Map<IProjectionMaterialGroup, IBatched>();
|
|
266
|
+
readonly #skinnedBatches = new Map<IProjectionBatchGroup, SkinnedBatch>();
|
|
267
|
+
readonly #state = new Map<Object3D, ISourceState>();
|
|
268
|
+
/** Exact-lane stand-ins, keyed by the source they mirror. */
|
|
269
|
+
readonly #proxies = new Map<Object3D, Object3D>();
|
|
270
|
+
readonly #lightProxies = new Map<Light, Light>();
|
|
271
|
+
/**
|
|
272
|
+
* Each source light's own `shadow.autoUpdate`, captured the frame the mirror took that light's
|
|
273
|
+
* map offline.
|
|
274
|
+
*
|
|
275
|
+
* While the mirror is what draws, the authored scene is not rendered, so the authored light's
|
|
276
|
+
* shadow map is never sampled: three builds a render's lighting from the scene it is handed,
|
|
277
|
+
* which holds the clone, not the source. The clone carries its own `LightShadow` and keeps
|
|
278
|
+
* updating; the source's map is dead work. Three reads `shadow.autoUpdate` per light in
|
|
279
|
+
* `ShadowNode.updateBefore`, so switching the source's off drops that map without touching the
|
|
280
|
+
* shadow camera, map size, bias or flags. The exact authored value comes back in `releaseAll`.
|
|
281
|
+
*/
|
|
282
|
+
readonly #lightShadowAutoUpdate = new Map<Light, boolean>();
|
|
283
|
+
readonly #exact = new Map<ProjectionExactReason, number>();
|
|
284
|
+
readonly #exactLane: IProjectionExactEntry[] = [];
|
|
285
|
+
readonly #extraExactPool: IProjectionExactEntry[] = [];
|
|
286
|
+
readonly #lightMembership = new WeakMap<Light, number>();
|
|
287
|
+
#lightGeneration = 0;
|
|
288
|
+
#exactLaneCount = 0;
|
|
289
|
+
#extraExactCount = 0;
|
|
290
|
+
#projectedObjects = 0;
|
|
291
|
+
#compileMs = 0;
|
|
292
|
+
#velocityEnabled: boolean;
|
|
293
|
+
/** Set when a member left a uniform group because its material drifted; read once per frame. */
|
|
294
|
+
#reclassified = false;
|
|
295
|
+
readonly #materialChecks: ProjectionMaterialChecks;
|
|
296
|
+
/** Where the drift sweep resumes: the group and the member offset within it. Persists frames. */
|
|
297
|
+
#sweepGroup = 0;
|
|
298
|
+
#sweepMember = 0;
|
|
299
|
+
/** Uniform members the plan holds, which is what the sweep walks and the bound divides. */
|
|
300
|
+
#sweepTotal = 0;
|
|
301
|
+
/**
|
|
302
|
+
* Materials already proved in the sweep in progress, so a material several members share is
|
|
303
|
+
* compared once per sweep rather than once per member. Bounded by the budget and cleared on
|
|
304
|
+
* every wrap, which is what makes the sweep's own cost a fixed number rather than a scene's.
|
|
305
|
+
*/
|
|
306
|
+
readonly #swept = new Set<Material>();
|
|
307
|
+
/** Materials this frame's sweep found drifted; every member holding one leaves its group. */
|
|
308
|
+
readonly #drifted = new Set<Material>();
|
|
309
|
+
|
|
310
|
+
constructor(velocityEnabled = false, materialChecks: ProjectionMaterialChecks = "spread") {
|
|
311
|
+
this.#velocityEnabled = velocityEnabled;
|
|
312
|
+
this.#materialChecks = materialChecks;
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
/** Rebuilds the private mirror when a temporal chain turns per-object history on or off. */
|
|
316
|
+
setVelocityEnabled(enabled: boolean): boolean {
|
|
317
|
+
if (this.#velocityEnabled === enabled) return false;
|
|
318
|
+
this.releaseAll();
|
|
319
|
+
this.#velocityEnabled = enabled;
|
|
320
|
+
return true;
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
get projectedObjects(): number {
|
|
324
|
+
return this.#projectedObjects;
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
get batchCount(): number {
|
|
328
|
+
return this.#batches.size + this.#materialBatches.size + this.#skinnedBatches.size;
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
/** Batches on the skinned lane — rigs sharing a geometry and material drawn from one palette. */
|
|
332
|
+
get skinnedBatchCount(): number {
|
|
333
|
+
return this.#skinnedBatches.size;
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
/** Batches on the instanced lane — one shared geometry instance folded into an `InstancedMesh`. */
|
|
337
|
+
get instancedBatchCount(): number {
|
|
338
|
+
return this.#batches.size;
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
/** Batches on the material lane — differing geometries packed into one `BatchedMesh` per material. */
|
|
342
|
+
get materialBatchCount(): number {
|
|
343
|
+
return this.#materialBatches.size;
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
get proxyCount(): number {
|
|
347
|
+
return this.#proxies.size;
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
get exactCounts(): ReadonlyMap<ProjectionExactReason, number> {
|
|
351
|
+
return this.#exact;
|
|
352
|
+
}
|
|
353
|
+
|
|
354
|
+
get compileMs(): number {
|
|
355
|
+
return this.#compileMs;
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
/**
|
|
359
|
+
* True when this frame's apply found a member whose material no longer matched the draw it was an
|
|
360
|
+
* instance of. The frame is still correct — that member is now drawn exactly — but the
|
|
361
|
+
* classification that put it there is stale, so the caller re-derives it before the next frame
|
|
362
|
+
* draws. Read once per frame, after `apply`.
|
|
363
|
+
*/
|
|
364
|
+
get reclassified(): boolean {
|
|
365
|
+
return this.#reclassified;
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
/** Which per-frame material check this mirror runs, for the report and the verdict line. */
|
|
369
|
+
get materialChecks(): ProjectionMaterialChecks {
|
|
370
|
+
return this.#materialChecks;
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
/** The per-frame ceiling on drift checks, or 0 when every material is proved every frame. */
|
|
374
|
+
get materialChecksPerFrame(): number {
|
|
375
|
+
return this.#materialChecks === "spread" ? MATERIAL_CHECKS_PER_FRAME : 0;
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
/**
|
|
379
|
+
* The worst frames a material edit can sit unproved for: one full sweep of the uniform members
|
|
380
|
+
* at the per-frame budget. 0 in `everyFrame` mode, where every material is proved every frame.
|
|
381
|
+
*/
|
|
382
|
+
get materialCheckStaleFrames(): number {
|
|
383
|
+
if (this.#materialChecks === "everyFrame") return 0;
|
|
384
|
+
return Math.ceil(this.#sweepTotal / MATERIAL_CHECKS_PER_FRAME);
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
/**
|
|
388
|
+
* Proves a bounded slice of the uniform members' materials, resuming where the last frame stopped.
|
|
389
|
+
*
|
|
390
|
+
* The check itself is unchanged — `uniformUnchanged`, whole own-value list, component reads and
|
|
391
|
+
* `defines` walk. What is bounded is how many members pay for it this frame, and a member whose
|
|
392
|
+
* material is proved drifted is marked here so the loop below ejects every member holding it, in
|
|
393
|
+
* this same frame, exactly as an eager per-member check would have.
|
|
394
|
+
*
|
|
395
|
+
* Deduplicated per sweep rather than per member: a material sixty-four cubes share is one fact,
|
|
396
|
+
* and comparing it sixty-four times a sweep is the cost this exists to remove. The cursor walks
|
|
397
|
+
* member *positions* and wraps, so a scene that grew or shrank mid-sweep still proves every
|
|
398
|
+
* member it currently holds within `ceil(members / budget)` frames.
|
|
399
|
+
*/
|
|
400
|
+
#sweepDrift(plan: IProjectionProjectPlan): void {
|
|
401
|
+
this.#drifted.clear();
|
|
402
|
+
let total = 0;
|
|
403
|
+
for (let index = 0; index < plan.batchGroupCount; index += 1) {
|
|
404
|
+
const group = plan.batchGroups[index] as IProjectionBatchGroup;
|
|
405
|
+
if ((group as Partial<IProjectionUniformGroup>).uniform === true) total += group.memberCount;
|
|
406
|
+
}
|
|
407
|
+
this.#sweepTotal = total;
|
|
408
|
+
let group = this.#sweepGroup;
|
|
409
|
+
let member = this.#sweepMember;
|
|
410
|
+
// A plan that shrank under the cursor leaves it past the end, which is the same thing as a
|
|
411
|
+
// finished sweep: start the next one from the top.
|
|
412
|
+
if (group >= plan.batchGroupCount) {
|
|
413
|
+
group = 0;
|
|
414
|
+
member = 0;
|
|
415
|
+
this.#swept.clear();
|
|
416
|
+
}
|
|
417
|
+
let budget = MATERIAL_CHECKS_PER_FRAME;
|
|
418
|
+
while (budget > 0 && group < plan.batchGroupCount) {
|
|
419
|
+
const candidate = plan.batchGroups[group] as IProjectionBatchGroup;
|
|
420
|
+
if ((candidate as Partial<IProjectionUniformGroup>).uniform !== true) {
|
|
421
|
+
group += 1;
|
|
422
|
+
member = 0;
|
|
423
|
+
continue;
|
|
424
|
+
}
|
|
425
|
+
if (member >= candidate.memberCount) {
|
|
426
|
+
group += 1;
|
|
427
|
+
member = 0;
|
|
428
|
+
continue;
|
|
429
|
+
}
|
|
430
|
+
const mesh = candidate.members[member] as Mesh;
|
|
431
|
+
const material = mesh.material as Material;
|
|
432
|
+
if (!this.#swept.has(material)) {
|
|
433
|
+
this.#swept.add(material);
|
|
434
|
+
if (!uniformUnchanged(material)) this.#drifted.add(material);
|
|
435
|
+
}
|
|
436
|
+
member += 1;
|
|
437
|
+
budget -= 1;
|
|
438
|
+
}
|
|
439
|
+
// Step past any group the last visited member exhausted, so a sweep that ends exactly on a
|
|
440
|
+
// slice boundary leaves the cursor on the next member rather than on a spent group — otherwise
|
|
441
|
+
// the next frame spends itself walking off the end and every material waits one frame longer
|
|
442
|
+
// than the bound the report states.
|
|
443
|
+
while (group < plan.batchGroupCount) {
|
|
444
|
+
const candidate = plan.batchGroups[group] as IProjectionBatchGroup;
|
|
445
|
+
if (
|
|
446
|
+
(candidate as Partial<IProjectionUniformGroup>).uniform === true &&
|
|
447
|
+
member < candidate.memberCount
|
|
448
|
+
)
|
|
449
|
+
break;
|
|
450
|
+
group += 1;
|
|
451
|
+
member = 0;
|
|
452
|
+
}
|
|
453
|
+
if (group < plan.batchGroupCount) {
|
|
454
|
+
this.#sweepGroup = group;
|
|
455
|
+
this.#sweepMember = member;
|
|
456
|
+
return;
|
|
457
|
+
}
|
|
458
|
+
// Off the end: the sweep covered every member, and the next one starts from the top with a
|
|
459
|
+
// fresh dedupe set rather than re-proving what this sweep just proved.
|
|
460
|
+
this.#swept.clear();
|
|
461
|
+
this.#sweepGroup = 0;
|
|
462
|
+
this.#sweepMember = 0;
|
|
463
|
+
}
|
|
464
|
+
|
|
465
|
+
/** Rebuilds exact-lane tallies and scratch from the scan without copying the entry objects. */
|
|
466
|
+
prepare(exactLane: readonly IProjectionExactEntry[], exactLaneCount: number): void {
|
|
467
|
+
this.#exact.clear();
|
|
468
|
+
this.#exactLaneCount = exactLaneCount;
|
|
469
|
+
this.#extraExactCount = 0;
|
|
470
|
+
for (let index = 0; index < exactLaneCount; index += 1) {
|
|
471
|
+
const entry = exactLane[index] as IProjectionExactEntry;
|
|
472
|
+
this.#exactLane[index] = entry;
|
|
473
|
+
const count = this.#exact.get(entry.reason) ?? 0;
|
|
474
|
+
this.#exact.set(entry.reason, count + 1);
|
|
475
|
+
}
|
|
476
|
+
}
|
|
477
|
+
|
|
478
|
+
/**
|
|
479
|
+
* Builds what a project plan describes and brings the mirror in line with the authored scene.
|
|
480
|
+
*
|
|
481
|
+
* Returns the unsupported-light reason when the scene's lights cannot be mirrored honestly —
|
|
482
|
+
* the caller then declines the whole frame. A batch that will not take an object gives up that
|
|
483
|
+
* object, not the scene: dropping several thousand batched props because one of them was
|
|
484
|
+
* awkward would be the fail-open rule applied at exactly the wrong granularity.
|
|
485
|
+
*
|
|
486
|
+
* `retireSources` is the sweep for objects that have left the scene, and a caller that has
|
|
487
|
+
* *proved* the scene's membership is unchanged — the projection's structure proof does exactly
|
|
488
|
+
* that — passes `false` and skips a per-instance walk that cannot find anything. Everything else
|
|
489
|
+
* here still runs: slots, stand-ins and lights are written every frame whatever the sweep does.
|
|
490
|
+
*/
|
|
491
|
+
apply(plan: IProjectionProjectPlan, retireSources = true): string | undefined {
|
|
492
|
+
const lightFailure = this.#syncLights(plan.lights, plan.lightCount);
|
|
493
|
+
if (lightFailure !== undefined) {
|
|
494
|
+
this.releaseAll();
|
|
495
|
+
return lightFailure;
|
|
496
|
+
}
|
|
497
|
+
// Groups below the floor join the objects that were never eligible. They keep their own draw,
|
|
498
|
+
// which is what they had. The scratch entries are pooled because this is a per-frame path.
|
|
499
|
+
this.#extraExactCount = 0;
|
|
500
|
+
for (let index = 0; index < plan.belowFloorCount; index += 1) {
|
|
501
|
+
const mesh = plan.belowFloor[index] as Mesh;
|
|
502
|
+
this.#release(mesh);
|
|
503
|
+
this.#appendExact(mesh, "tooFewToBatch");
|
|
504
|
+
}
|
|
505
|
+
// A batch that will not take an object gives up that object, not the scene. Dropping several
|
|
506
|
+
// thousand batched props because one of them was awkward would be the fail-open rule applied
|
|
507
|
+
// at exactly the wrong granularity.
|
|
508
|
+
this.#projectedObjects = 0;
|
|
509
|
+
this.#reclassified = false;
|
|
510
|
+
// Before the member loops, because the loops read what it found: a member whose material this
|
|
511
|
+
// frame's slice proved drifted leaves the group here rather than at the next sweep's turn.
|
|
512
|
+
if (this.#materialChecks === "spread") this.#sweepDrift(plan);
|
|
513
|
+
for (let index = 0; index < plan.batchGroupCount; index += 1) {
|
|
514
|
+
const group = plan.batchGroups[index] as IProjectionBatchGroup;
|
|
515
|
+
const batch = this.#ensureBatch(group);
|
|
516
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
517
|
+
const mesh = group.members[member] as Mesh;
|
|
518
|
+
const refused =
|
|
519
|
+
batch === undefined ? "unsupportedGeometry" : this.#syncBatched(batch, mesh);
|
|
520
|
+
if (refused === undefined) {
|
|
521
|
+
this.#projectedObjects += 1;
|
|
522
|
+
continue;
|
|
523
|
+
}
|
|
524
|
+
// Each refusal names its own cause and every refused mesh keeps a draw of its own: a batch
|
|
525
|
+
// that will not take an object gives up that object, not the scene, and a member whose
|
|
526
|
+
// material drifted out of its group is drawn exactly until the classification catches up.
|
|
527
|
+
this.#release(mesh);
|
|
528
|
+
this.#appendExact(mesh, refused);
|
|
529
|
+
}
|
|
530
|
+
if (batch !== undefined) this.#flushBatch(batch);
|
|
531
|
+
}
|
|
532
|
+
this.#applyMaterialGroups(plan);
|
|
533
|
+
this.#applySkinnedGroups(plan);
|
|
534
|
+
for (let index = 0; index < this.#exactLaneCount; index += 1) {
|
|
535
|
+
const entry = this.#exactLane[index] as IProjectionExactEntry;
|
|
536
|
+
const object = exactObject(entry);
|
|
537
|
+
// An object can change lane while staying in the scene — a material turning transparent, a
|
|
538
|
+
// `renderOrder` being set, a plain mesh swapped for a skinned one. Its batch instance has to
|
|
539
|
+
// go as it acquires a proxy, or the frame draws it twice: once batched and once exactly.
|
|
540
|
+
this.#release(object);
|
|
541
|
+
this.#syncProxy(object);
|
|
542
|
+
}
|
|
543
|
+
if (retireSources) this.#retire(plan.seen, plan.lights, plan.lightCount);
|
|
544
|
+
// After retirement, so a slot freed this frame uploads collapsed rather than one frame late.
|
|
545
|
+
for (const batch of this.#skinnedBatches.values()) batch.end();
|
|
546
|
+
this.#clearExactScratch();
|
|
547
|
+
return undefined;
|
|
548
|
+
}
|
|
549
|
+
|
|
550
|
+
/**
|
|
551
|
+
* Applies the plan's skinned groups: one palette draw per group, each rig a slot re-posed from
|
|
552
|
+
* its own skeleton every frame.
|
|
553
|
+
*
|
|
554
|
+
* The world transform is folded into the palette, which is exact only for a similarity
|
|
555
|
+
* transform, so a rig scaled unevenly or mirrored keeps its own draw with that reason named.
|
|
556
|
+
*/
|
|
557
|
+
#applySkinnedGroups(plan: IProjectionProjectPlan): void {
|
|
558
|
+
for (let index = 0; index < plan.skinnedGroupCount; index += 1) {
|
|
559
|
+
const group = plan.skinnedGroups[index] as IProjectionBatchGroup;
|
|
560
|
+
const batch = this.#ensureSkinned(group);
|
|
561
|
+
batch?.begin();
|
|
562
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
563
|
+
const rig = group.members[member] as SkinnedMesh;
|
|
564
|
+
const refused = batch === undefined ? "unsupportedGeometry" : this.#syncSkinned(batch, rig);
|
|
565
|
+
if (refused === undefined) {
|
|
566
|
+
this.#projectedObjects += 1;
|
|
567
|
+
continue;
|
|
568
|
+
}
|
|
569
|
+
this.#release(rig);
|
|
570
|
+
this.#appendExact(rig, refused);
|
|
571
|
+
}
|
|
572
|
+
}
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
/** Poses one rig in its palette slot, or names why it keeps a draw of its own. */
|
|
576
|
+
#syncSkinned(batch: SkinnedBatch, rig: SkinnedMesh): ProjectionExactReason | undefined {
|
|
577
|
+
if (!isSimilarityTransform(rig.matrixWorld.elements)) {
|
|
578
|
+
return rig.matrixWorld.determinant() <= 0 ? "negativeScale" : "nonUniformScale";
|
|
579
|
+
}
|
|
580
|
+
const slot = this.#claimSkinned(batch, rig);
|
|
581
|
+
if (slot === undefined) return "batchOverflow";
|
|
582
|
+
const state = this.#state.get(rig) as ISourceState;
|
|
583
|
+
const visible = this.#visibleInWorld(rig);
|
|
584
|
+
if (!visible) batch.hide(slot);
|
|
585
|
+
else {
|
|
586
|
+
// A rig coming back into view has collapsed history; it starts from its own pose.
|
|
587
|
+
if (!state.visible) batch.restart(slot);
|
|
588
|
+
batch.write(slot, rig);
|
|
589
|
+
}
|
|
590
|
+
state.visible = visible;
|
|
591
|
+
state.matrixWorld.copy(rig.matrixWorld);
|
|
592
|
+
state.material = rig.material;
|
|
593
|
+
return undefined;
|
|
594
|
+
}
|
|
595
|
+
|
|
596
|
+
#claimSkinned(batch: SkinnedBatch, rig: SkinnedMesh): number | undefined {
|
|
597
|
+
const previous = this.#state.get(rig);
|
|
598
|
+
if (previous !== undefined && previous.batch !== batch) this.#release(rig);
|
|
599
|
+
this.#releaseProxy(rig);
|
|
600
|
+
const known = batch.instances.has(rig);
|
|
601
|
+
const slot = batch.claim(rig);
|
|
602
|
+
if (slot === undefined) return undefined;
|
|
603
|
+
if (!known) {
|
|
604
|
+
this.#state.set(rig, {
|
|
605
|
+
matrixWorld: new Matrix4(),
|
|
606
|
+
visible: true,
|
|
607
|
+
geometry: rig.geometry,
|
|
608
|
+
material: rig.material,
|
|
609
|
+
batch,
|
|
610
|
+
red: Number.NaN,
|
|
611
|
+
green: Number.NaN,
|
|
612
|
+
blue: Number.NaN,
|
|
613
|
+
});
|
|
614
|
+
}
|
|
615
|
+
return slot;
|
|
616
|
+
}
|
|
617
|
+
|
|
618
|
+
/** The palette draw for one skinned group, rebuilt at a larger size when the group outgrows it. */
|
|
619
|
+
#ensureSkinned(group: IProjectionBatchGroup): SkinnedBatch | undefined {
|
|
620
|
+
const existing = this.#skinnedBatches.get(group);
|
|
621
|
+
if (existing !== undefined && existing.capacity >= group.memberCount) return existing;
|
|
622
|
+
const startedAt = globalThis.performance?.now() ?? 0;
|
|
623
|
+
const first = group.members[0] as SkinnedMesh;
|
|
624
|
+
const rigBytes = first.skeleton.bones.length * 64;
|
|
625
|
+
const capacity = Math.min(
|
|
626
|
+
Math.max(BATCH_MIN_SLOTS, Math.ceil(group.memberCount * BATCH_GROWTH)),
|
|
627
|
+
Math.floor(PALETTE_BINDING_BYTES / rigBytes),
|
|
628
|
+
);
|
|
629
|
+
if (existing !== undefined) {
|
|
630
|
+
if (existing.capacity >= capacity) return existing;
|
|
631
|
+
this.#disposeSkinned(existing);
|
|
632
|
+
}
|
|
633
|
+
let batch: SkinnedBatch;
|
|
634
|
+
try {
|
|
635
|
+
batch = new SkinnedBatch({ first, capacity, velocity: this.#velocityEnabled });
|
|
636
|
+
} catch {
|
|
637
|
+
return undefined;
|
|
638
|
+
}
|
|
639
|
+
this.#skinnedBatches.set(group, batch);
|
|
640
|
+
this.scene.add(batch.mesh);
|
|
641
|
+
this.#compileMs += (globalThis.performance?.now() ?? 0) - startedAt;
|
|
642
|
+
return batch;
|
|
643
|
+
}
|
|
644
|
+
|
|
645
|
+
#disposeSkinned(batch: SkinnedBatch): void {
|
|
646
|
+
for (const object of batch.instances.keys()) this.#state.delete(object);
|
|
647
|
+
batch.dispose();
|
|
648
|
+
for (const [group, candidate] of this.#skinnedBatches) {
|
|
649
|
+
if (candidate === batch) this.#skinnedBatches.delete(group);
|
|
650
|
+
}
|
|
651
|
+
}
|
|
652
|
+
|
|
653
|
+
#appendExact(object: Object3D, reason: ProjectionExactReason): void {
|
|
654
|
+
const index = this.#extraExactCount;
|
|
655
|
+
this.#extraExactCount += 1;
|
|
656
|
+
let entry = this.#extraExactPool[index];
|
|
657
|
+
if (entry === undefined) {
|
|
658
|
+
entry = { object, reason };
|
|
659
|
+
this.#extraExactPool.push(entry);
|
|
660
|
+
} else {
|
|
661
|
+
entry.object = object;
|
|
662
|
+
entry.reason = reason;
|
|
663
|
+
}
|
|
664
|
+
this.#exactLane[this.#exactLaneCount] = entry;
|
|
665
|
+
this.#exactLaneCount += 1;
|
|
666
|
+
const count = this.#exact.get(reason) ?? 0;
|
|
667
|
+
this.#exact.set(reason, count + 1);
|
|
668
|
+
}
|
|
669
|
+
|
|
670
|
+
/**
|
|
671
|
+
* Applies the plan's material-keyed groups: one `BatchedMesh` per group, its members as packed
|
|
672
|
+
* instances.
|
|
673
|
+
*
|
|
674
|
+
* `BatchedMesh.setMatrixAt` does not support negatively scaled matrices — a mirrored source
|
|
675
|
+
* would draw inside-out under front-face culling. The scan reads no world matrices by design,
|
|
676
|
+
* so the gate lives here where they are fresh. Counting viable members before building keeps
|
|
677
|
+
* the invariant that a projected frame never hands the renderer more draw candidates than the
|
|
678
|
+
* authored scene has: a group that cannot fill a batch never builds one.
|
|
679
|
+
*/
|
|
680
|
+
#applyMaterialGroups(plan: IProjectionProjectPlan): void {
|
|
681
|
+
for (let index = 0; index < plan.materialGroupCount; index += 1) {
|
|
682
|
+
const group = plan.materialGroups[index] as IProjectionMaterialGroup;
|
|
683
|
+
if (this.#velocityEnabled && !isBatchedMeshVelocityPatched()) {
|
|
684
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
685
|
+
const mesh = group.members[member] as Mesh;
|
|
686
|
+
this.#release(mesh);
|
|
687
|
+
this.#appendExact(mesh, "batchVelocityPatchMissing");
|
|
688
|
+
}
|
|
689
|
+
continue;
|
|
690
|
+
}
|
|
691
|
+
let viableCount = 0;
|
|
692
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
693
|
+
if ((group.members[member] as Mesh).matrixWorld.determinant() > 0) viableCount += 1;
|
|
694
|
+
}
|
|
695
|
+
const attempted = viableCount >= MIN_BATCH_MEMBERS;
|
|
696
|
+
const batch = attempted ? this.#ensureBatched(group) : undefined;
|
|
697
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
698
|
+
const mesh = group.members[member] as Mesh;
|
|
699
|
+
const mirrored = mesh.matrixWorld.determinant() <= 0;
|
|
700
|
+
if (batch !== undefined && !mirrored && this.#syncBatchedMaterial(batch, mesh)) {
|
|
701
|
+
this.#projectedObjects += 1;
|
|
702
|
+
continue;
|
|
703
|
+
}
|
|
704
|
+
// The same report discipline as the instanced loop: each refusal names its own cause,
|
|
705
|
+
// and every refused mesh keeps a draw of its own.
|
|
706
|
+
const reason = mirrored
|
|
707
|
+
? "negativeScale"
|
|
708
|
+
: !attempted
|
|
709
|
+
? "tooFewToBatch"
|
|
710
|
+
: batch === undefined
|
|
711
|
+
? "unsupportedGeometry"
|
|
712
|
+
: "batchOverflow";
|
|
713
|
+
this.#release(mesh);
|
|
714
|
+
this.#appendExact(mesh, reason);
|
|
715
|
+
}
|
|
716
|
+
}
|
|
717
|
+
}
|
|
718
|
+
|
|
719
|
+
/**
|
|
720
|
+
* Who owns each object this mirror hands the renderer, built on demand for a diagnostic.
|
|
721
|
+
*
|
|
722
|
+
* The mirror is what the renderer sees, so a per-object cost report reading the authored scene
|
|
723
|
+
* would attribute the frame to objects that were never submitted. Keyed by the rendered object:
|
|
724
|
+
* an exact stand-in names its one source, a batch names every source it folded. Nothing is
|
|
725
|
+
* retained — the map is the caller's, and building it costs one pass over the live entries.
|
|
726
|
+
*/
|
|
727
|
+
describeOwnership(): Map<Object3D, IGeometryOwnership> {
|
|
728
|
+
const ownership = new Map<Object3D, IGeometryOwnership>();
|
|
729
|
+
for (const [source, proxy] of this.#proxies) {
|
|
730
|
+
ownership.set(proxy, { kind: "exact", sources: [source] });
|
|
731
|
+
}
|
|
732
|
+
for (const batch of this.#batches.values()) {
|
|
733
|
+
ownership.set(batch.mesh, {
|
|
734
|
+
kind: "instancedBatch",
|
|
735
|
+
sources: [...batch.instances.keys()],
|
|
736
|
+
});
|
|
737
|
+
}
|
|
738
|
+
for (const batch of this.#materialBatches.values()) {
|
|
739
|
+
ownership.set(batch.mesh, {
|
|
740
|
+
kind: "materialBatch",
|
|
741
|
+
sources: [...batch.instances.keys()],
|
|
742
|
+
});
|
|
743
|
+
}
|
|
744
|
+
for (const batch of this.#skinnedBatches.values()) {
|
|
745
|
+
ownership.set(batch.mesh, {
|
|
746
|
+
kind: "instancedBatch",
|
|
747
|
+
sources: [...batch.instances.keys()],
|
|
748
|
+
});
|
|
749
|
+
}
|
|
750
|
+
return ownership;
|
|
751
|
+
}
|
|
752
|
+
|
|
753
|
+
/** Drops sources that have left the authored scene, so nothing draws what the game removed. */
|
|
754
|
+
#retire(
|
|
755
|
+
seen: { has(object: Object3D): boolean },
|
|
756
|
+
lights: readonly (Light | undefined)[],
|
|
757
|
+
lightCount: number,
|
|
758
|
+
): void {
|
|
759
|
+
this.#retireBatches(seen);
|
|
760
|
+
this.#retireMaterialBatches(seen);
|
|
761
|
+
this.#retireSkinnedBatches(seen);
|
|
762
|
+
this.#retireProxies(seen);
|
|
763
|
+
this.#retireLights(lights, lightCount);
|
|
764
|
+
}
|
|
765
|
+
|
|
766
|
+
#retireBatches(seen: { has(object: Object3D): boolean }): void {
|
|
767
|
+
for (const batch of this.#batches.values()) {
|
|
768
|
+
for (const object of batch.instances.keys()) {
|
|
769
|
+
if (seen.has(object)) continue;
|
|
770
|
+
const slot = batch.instances.get(object) as number;
|
|
771
|
+
// Collapsed and returned to the free list rather than removed: an `InstancedMesh` has a
|
|
772
|
+
// fixed slot count, and recycling is what lets a level stream objects in and out without
|
|
773
|
+
// rebuilding its draws each time.
|
|
774
|
+
if (slot >= 0) {
|
|
775
|
+
batch.mesh.setMatrixAt(slot, ZERO_MATRIX);
|
|
776
|
+
batch.mesh.instanceMatrix.needsUpdate = true;
|
|
777
|
+
}
|
|
778
|
+
batch.instances.delete(object);
|
|
779
|
+
if (slot >= 0) batch.free.push(slot);
|
|
780
|
+
this.#state.delete(object);
|
|
781
|
+
}
|
|
782
|
+
if (batch.instances.size === 0) this.#disposeBatch(batch);
|
|
783
|
+
}
|
|
784
|
+
}
|
|
785
|
+
|
|
786
|
+
/** Retires material-keyed batches on the same hidden-not-deleted free-list discipline. */
|
|
787
|
+
#retireMaterialBatches(seen: { has(object: Object3D): boolean }): void {
|
|
788
|
+
for (const batch of this.#materialBatches.values()) {
|
|
789
|
+
for (const object of batch.instances.keys()) {
|
|
790
|
+
if (seen.has(object)) continue;
|
|
791
|
+
const slot = batch.instances.get(object) as number;
|
|
792
|
+
batch.mesh.setVisibleAt(slot, false);
|
|
793
|
+
batch.instances.delete(object);
|
|
794
|
+
batch.free.push(slot);
|
|
795
|
+
this.#state.delete(object);
|
|
796
|
+
}
|
|
797
|
+
if (batch.instances.size === 0) this.#disposeBatched(batch);
|
|
798
|
+
}
|
|
799
|
+
}
|
|
800
|
+
|
|
801
|
+
#retireSkinnedBatches(seen: { has(object: Object3D): boolean }): void {
|
|
802
|
+
for (const batch of this.#skinnedBatches.values()) {
|
|
803
|
+
for (const object of batch.instances.keys()) {
|
|
804
|
+
if (seen.has(object)) continue;
|
|
805
|
+
batch.release(object);
|
|
806
|
+
this.#state.delete(object);
|
|
807
|
+
}
|
|
808
|
+
if (batch.instances.size === 0) this.#disposeSkinned(batch);
|
|
809
|
+
}
|
|
810
|
+
}
|
|
811
|
+
|
|
812
|
+
#retireProxies(seen: { has(object: Object3D): boolean }): void {
|
|
813
|
+
for (const object of this.#proxies.keys()) {
|
|
814
|
+
if (seen.has(object)) continue;
|
|
815
|
+
const proxy = this.#proxies.get(object) as Object3D;
|
|
816
|
+
this.scene.remove(proxy);
|
|
817
|
+
this.#proxies.delete(object);
|
|
818
|
+
this.#state.delete(object);
|
|
819
|
+
}
|
|
820
|
+
}
|
|
821
|
+
|
|
822
|
+
#retireLights(lights: readonly (Light | undefined)[], lightCount: number): void {
|
|
823
|
+
this.#lightGeneration += 1;
|
|
824
|
+
for (let index = 0; index < lightCount; index += 1) {
|
|
825
|
+
const light = lights[index] as Light;
|
|
826
|
+
this.#lightMembership.set(light, this.#lightGeneration);
|
|
827
|
+
}
|
|
828
|
+
for (const light of this.#lightProxies.keys()) {
|
|
829
|
+
if (this.#lightMembership.get(light) === this.#lightGeneration) continue;
|
|
830
|
+
const proxy = this.#lightProxies.get(light) as Light;
|
|
831
|
+
this.scene.remove(proxy);
|
|
832
|
+
this.#lightProxies.delete(light);
|
|
833
|
+
// A light that leaves the mirror gets its shadow update back now, so a light that returns
|
|
834
|
+
// later is cloned from a source that still updates rather than from the offline state.
|
|
835
|
+
this.#restoreLightShadow(light);
|
|
836
|
+
}
|
|
837
|
+
}
|
|
838
|
+
|
|
839
|
+
/** Puts a source light's own shadow-update state back and forgets it. */
|
|
840
|
+
#restoreLightShadow(light: Light): void {
|
|
841
|
+
const original = this.#lightShadowAutoUpdate.get(light);
|
|
842
|
+
if (original === undefined) return;
|
|
843
|
+
this.#lightShadowAutoUpdate.delete(light);
|
|
844
|
+
const shadow = (light as Light & { shadow?: { autoUpdate: boolean } }).shadow;
|
|
845
|
+
if (shadow !== undefined) shadow.autoUpdate = original;
|
|
846
|
+
}
|
|
847
|
+
|
|
848
|
+
/**
|
|
849
|
+
* Mirrors the scene's lights.
|
|
850
|
+
*
|
|
851
|
+
* A light cannot be in two graphs at once and moving the game's own light into the mirror would
|
|
852
|
+
* be exactly the destructive rewrite this class exists to stop, so each is cloned once and then
|
|
853
|
+
* kept in step. Only what a game changes at runtime is synchronized; a light form this does not
|
|
854
|
+
* recognize returns false and the whole frame goes to the authored scene, because a scene lit
|
|
855
|
+
* differently from the way the game lit it is a wrong picture, not a slow one.
|
|
856
|
+
*/
|
|
857
|
+
#syncLights(lights: readonly (Light | undefined)[], lightCount: number): string | undefined {
|
|
858
|
+
for (let index = 0; index < lightCount; index += 1) {
|
|
859
|
+
const light = lights[index] as Light;
|
|
860
|
+
let proxy = this.#lightProxies.get(light);
|
|
861
|
+
if (proxy === undefined) {
|
|
862
|
+
const cloned = light.clone() as Light & { target?: Object3D };
|
|
863
|
+
if (!isLight(cloned)) return `a ${light.type} could not be mirrored`;
|
|
864
|
+
// A spot or directional light aims at a target object that lives in the game's graph. The
|
|
865
|
+
// clone's own target is a fresh object at the origin, so the mirror would light a
|
|
866
|
+
// different direction; pointing the clone at the authored target keeps the aim.
|
|
867
|
+
const target = (light as Light & { target?: Object3D }).target;
|
|
868
|
+
if (target !== undefined) cloned.target = target;
|
|
869
|
+
cloned.matrixAutoUpdate = false;
|
|
870
|
+
proxy = cloned;
|
|
871
|
+
this.#lightProxies.set(light, cloned);
|
|
872
|
+
this.scene.add(cloned);
|
|
873
|
+
}
|
|
874
|
+
// The local matrix, for the same reason the mesh proxies use it: the renderer recomposes
|
|
875
|
+
// every child's `matrixWorld` from its local matrix, so a light written the other way lights
|
|
876
|
+
// the scene from the origin regardless of where the game put it.
|
|
877
|
+
proxy.matrix.copy(light.matrixWorld);
|
|
878
|
+
proxy.visible = light.visible;
|
|
879
|
+
proxy.intensity = light.intensity;
|
|
880
|
+
(proxy.color as Color | undefined)?.copy(light.color as Color);
|
|
881
|
+
proxy.castShadow = light.castShadow;
|
|
882
|
+
proxy.layers.mask = light.layers.mask;
|
|
883
|
+
// Cone and falloff are runtime surface too: a flashlight zoom or a muzzle-flash decay
|
|
884
|
+
// changes these per frame, and frozen first-frame values would render the scene lit
|
|
885
|
+
// differently than the game lit it.
|
|
886
|
+
if ((light as { isSpotLight?: boolean }).isSpotLight === true) {
|
|
887
|
+
const spot = light as SpotLight;
|
|
888
|
+
const spotProxy = proxy as SpotLight;
|
|
889
|
+
spotProxy.angle = spot.angle;
|
|
890
|
+
spotProxy.penumbra = spot.penumbra;
|
|
891
|
+
spotProxy.distance = spot.distance;
|
|
892
|
+
spotProxy.decay = spot.decay;
|
|
893
|
+
spotProxy.power = spot.power;
|
|
894
|
+
}
|
|
895
|
+
if ((light as { isPointLight?: boolean }).isPointLight === true) {
|
|
896
|
+
const point = light as PointLight;
|
|
897
|
+
const pointProxy = proxy as PointLight;
|
|
898
|
+
pointProxy.distance = point.distance;
|
|
899
|
+
pointProxy.decay = point.decay;
|
|
900
|
+
pointProxy.power = point.power;
|
|
901
|
+
}
|
|
902
|
+
// The clone above copied `autoUpdate` before it was switched off, so the drawn light keeps
|
|
903
|
+
// its shadow. Only the source — whose map nothing samples this frame — is taken offline.
|
|
904
|
+
const shadow = (light as Light & { shadow?: { autoUpdate: boolean } }).shadow;
|
|
905
|
+
if (
|
|
906
|
+
shadow !== undefined &&
|
|
907
|
+
shadow.autoUpdate === true &&
|
|
908
|
+
!this.#lightShadowAutoUpdate.has(light)
|
|
909
|
+
) {
|
|
910
|
+
this.#lightShadowAutoUpdate.set(light, shadow.autoUpdate);
|
|
911
|
+
shadow.autoUpdate = false;
|
|
912
|
+
}
|
|
913
|
+
}
|
|
914
|
+
return undefined;
|
|
915
|
+
}
|
|
916
|
+
/**
|
|
917
|
+
* Puts an eligible mesh in a batch and keeps it there, in step with its source.
|
|
918
|
+
*
|
|
919
|
+
* The mirror holds the game's own geometry and material by reference, never a copy, so a game
|
|
920
|
+
* that recolours a material recolours every draw sharing it and a game that streams into a
|
|
921
|
+
* geometry changes what draws without the mirror being told anything at all. Nothing here
|
|
922
|
+
* decides how anything looks; it decides only which draw a thing is part of.
|
|
923
|
+
*
|
|
924
|
+
* This is where "the game may change anything at any time" is paid for. Each supported property
|
|
925
|
+
* is compared against what was last pushed and written in place when it differs — a moved object
|
|
926
|
+
* is a matrix write, a hidden one a collapsed matrix. Nothing rebuilds, which is what makes
|
|
927
|
+
* reconciling every frame affordable instead of guessing once at startup and being wrong for the
|
|
928
|
+
* rest of the session.
|
|
929
|
+
*
|
|
930
|
+
* A uniform batch is the one draw that cannot hold the game's material, because it stands for
|
|
931
|
+
* many of them. So the colour is the only value it writes per member, and every *other* value its
|
|
932
|
+
* shared clone was built from is proved unchanged first: a member that drifted leaves the group
|
|
933
|
+
* rather than draw with a roughness, a map or an alpha that is not its own. That is a
|
|
934
|
+
* reclassification rather than a fallback, so the caller is told and the next frame re-derives it.
|
|
935
|
+
*
|
|
936
|
+
* Which frame proves it is the mode's business, not the ejection's. `everyFrame` compares here
|
|
937
|
+
* for every member; `spread` compares a bounded slice of the members in `#sweepDrift` and reads
|
|
938
|
+
* its answer here, so a drifted material costs every member holding it the same frame it was
|
|
939
|
+
* found in, and costs a settled frame nothing.
|
|
940
|
+
*/
|
|
941
|
+
#syncBatched(target: IBatch, mesh: Mesh): ProjectionExactReason | undefined {
|
|
942
|
+
const material = mesh.material as Material;
|
|
943
|
+
const geometry = mesh.geometry;
|
|
944
|
+
let state = this.#state.get(mesh);
|
|
945
|
+
|
|
946
|
+
// Read before the group comparison below, because a member whose material no longer matches
|
|
947
|
+
// the group is leaving whichever batch it holds: the one it is in would draw it with a
|
|
948
|
+
// roughness, a map or an alpha that is not its own.
|
|
949
|
+
if (
|
|
950
|
+
target.uniform &&
|
|
951
|
+
state !== undefined &&
|
|
952
|
+
(this.#materialChecks === "everyFrame"
|
|
953
|
+
? !uniformUnchanged(material)
|
|
954
|
+
: this.#drifted.size > 0 && this.#drifted.has(material))
|
|
955
|
+
) {
|
|
956
|
+
this.#reclassified = true;
|
|
957
|
+
this.#release(mesh);
|
|
958
|
+
return "materialChanged";
|
|
959
|
+
}
|
|
960
|
+
// A geometry, material or flag change moves the object to a different batch entirely, so the
|
|
961
|
+
// old slot is released and it re-enters as if it were new. The group identity covers the
|
|
962
|
+
// shadow flags and layer mask, which change nothing about where an object is but everything
|
|
963
|
+
// about which draw it may share. The release takes the state with it, and the slot is gone
|
|
964
|
+
// with it, so the allocation below is what refills both.
|
|
965
|
+
if (state !== undefined && state.batch !== target) {
|
|
966
|
+
this.#release(mesh);
|
|
967
|
+
state = undefined;
|
|
968
|
+
}
|
|
969
|
+
// A mesh that was on the exact lane last frame and is batchable now must not keep its
|
|
970
|
+
// stand-in, or it draws twice. A scene with no stand-ins is the common case, and this is a map
|
|
971
|
+
// probe per object per frame, so the empty check comes before it.
|
|
972
|
+
if (this.#proxies.size > 0) this.#releaseProxy(mesh);
|
|
973
|
+
|
|
974
|
+
let slot = target.instances.get(mesh);
|
|
975
|
+
if (slot === undefined) {
|
|
976
|
+
slot = target.free.pop();
|
|
977
|
+
if (slot === undefined) {
|
|
978
|
+
if (target.used >= target.capacity) return "batchOverflow";
|
|
979
|
+
slot = target.used;
|
|
980
|
+
target.used += 1;
|
|
981
|
+
}
|
|
982
|
+
target.instances.set(mesh, slot);
|
|
983
|
+
// Deliberately unequal to anything real, so the first reconcile below writes the matrix
|
|
984
|
+
// and the visibility rather than assuming the new slot already carries them.
|
|
985
|
+
state = {
|
|
986
|
+
matrixWorld: new Matrix4().multiplyScalar(0),
|
|
987
|
+
visible: !mesh.visible,
|
|
988
|
+
geometry,
|
|
989
|
+
material,
|
|
990
|
+
batch: target,
|
|
991
|
+
red: Number.NaN,
|
|
992
|
+
green: Number.NaN,
|
|
993
|
+
blue: Number.NaN,
|
|
994
|
+
};
|
|
995
|
+
this.#state.set(mesh, state);
|
|
996
|
+
}
|
|
997
|
+
const current = state as ISourceState;
|
|
998
|
+
// Ancestor visibility, not the object's own flag: a prop under a hidden group does not draw,
|
|
999
|
+
// and a batch has no hierarchy to inherit that from.
|
|
1000
|
+
const visible = this.#visibleInWorld(mesh);
|
|
1001
|
+
// three's `equals` is the element-wise compare, and a host keeping matrices outside the script
|
|
1002
|
+
// engine runs it in place instead of copying 32 numbers in.
|
|
1003
|
+
if (visible !== current.visible || !current.matrixWorld.equals(mesh.matrixWorld)) {
|
|
1004
|
+
current.matrixWorld.copy(mesh.matrixWorld);
|
|
1005
|
+
current.visible = visible;
|
|
1006
|
+
// An `InstancedMesh` has no per-instance visibility flag, so a hidden object is given a
|
|
1007
|
+
// collapsed transform. Every one of its triangles then has zero area and is discarded before
|
|
1008
|
+
// rasterisation — the same trick the pass this replaces used, and the only one available
|
|
1009
|
+
// that does not disturb the other instances.
|
|
1010
|
+
target.mesh.setMatrixAt(slot, visible ? mesh.matrixWorld : ZERO_MATRIX);
|
|
1011
|
+
// One flag per batch rather than one per object, applied by the caller: the buffer is
|
|
1012
|
+
// uploaded once whatever wrote into it, and a version bump per object is a setter call per
|
|
1013
|
+
// object for the same single upload.
|
|
1014
|
+
target.dirty = true;
|
|
1015
|
+
}
|
|
1016
|
+
if (target.uniform) {
|
|
1017
|
+
// The only per-member value a uniform draw carries, and the only one a game may move without
|
|
1018
|
+
// leaving the group: three floats against what this slot last carried. The shared clone's
|
|
1019
|
+
// colour is white, so what three's node material draws is the source colour exactly.
|
|
1020
|
+
const color = baseColorOf(material) as Color;
|
|
1021
|
+
if (current.red !== color.r || current.green !== color.g || current.blue !== color.b) {
|
|
1022
|
+
target.mesh.setColorAt(slot, color);
|
|
1023
|
+
current.red = color.r;
|
|
1024
|
+
current.green = color.g;
|
|
1025
|
+
current.blue = color.b;
|
|
1026
|
+
target.colorsDirty = true;
|
|
1027
|
+
}
|
|
1028
|
+
}
|
|
1029
|
+
current.geometry = geometry;
|
|
1030
|
+
current.material = material;
|
|
1031
|
+
current.batch = target;
|
|
1032
|
+
return undefined;
|
|
1033
|
+
}
|
|
1034
|
+
|
|
1035
|
+
/** Whether the game currently wants this object drawn, ancestors included. */
|
|
1036
|
+
#visibleInWorld(object: Object3D): boolean {
|
|
1037
|
+
// A host whose parents cost a call and an allocation each answers for the whole chain.
|
|
1038
|
+
const host = (object as { __tnVisibleInWorld?: () => boolean }).__tnVisibleInWorld;
|
|
1039
|
+
if (typeof host === "function") return host.call(object);
|
|
1040
|
+
for (let node: Object3D | null = object; node !== null; node = node.parent) {
|
|
1041
|
+
if (!node.visible) return false;
|
|
1042
|
+
}
|
|
1043
|
+
return true;
|
|
1044
|
+
}
|
|
1045
|
+
|
|
1046
|
+
/**
|
|
1047
|
+
* Ends a batch's frame: one upload flag and one draw count for every slot written into it.
|
|
1048
|
+
*
|
|
1049
|
+
* Both were per object before, and both are per buffer: `needsUpdate` is a version bump the
|
|
1050
|
+
* renderer reads once, whatever wrote into the array behind it, and `count` is the number of slots
|
|
1051
|
+
* the batch has handed out — which only the last object of the loop could state correctly anyway.
|
|
1052
|
+
*/
|
|
1053
|
+
#flushBatch(batch: IBatch): void {
|
|
1054
|
+
batch.mesh.count = batch.used;
|
|
1055
|
+
if (batch.dirty) {
|
|
1056
|
+
batch.dirty = false;
|
|
1057
|
+
batch.mesh.instanceMatrix.needsUpdate = true;
|
|
1058
|
+
}
|
|
1059
|
+
if (!batch.colorsDirty) return;
|
|
1060
|
+
batch.colorsDirty = false;
|
|
1061
|
+
(batch.mesh.instanceColor as { needsUpdate: boolean }).needsUpdate = true;
|
|
1062
|
+
}
|
|
1063
|
+
|
|
1064
|
+
/**
|
|
1065
|
+
* The batch for one (geometry, material, flags) group, sized to hold it.
|
|
1066
|
+
*
|
|
1067
|
+
* `InstancedMesh` rather than `BatchedMesh`, and the difference is measured rather than
|
|
1068
|
+
* stylistic. Three's WebGPU backend has no multi-draw path: it walks a `BatchedMesh` and issues
|
|
1069
|
+
* one `drawIndexed` per sub-draw, so a thousand batched objects still cost a thousand draw
|
|
1070
|
+
* commands. An `InstancedMesh` is one draw command for the whole group. It also references the
|
|
1071
|
+
* game's geometry rather than copying it into a private buffer, so a game streaming into its own
|
|
1072
|
+
* attribute needs no re-upload here at all — the batch is already looking at the same array.
|
|
1073
|
+
*
|
|
1074
|
+
* The price is that a group must share one geometry, where a `BatchedMesh` can hold several. A
|
|
1075
|
+
* level of mixed props therefore gets one draw per distinct prop kind instead of one per
|
|
1076
|
+
* material, which on the workloads measured is still the overwhelming majority of the reduction.
|
|
1077
|
+
*/
|
|
1078
|
+
#ensureBatch(group: IProjectionBatchGroup): IBatch | undefined {
|
|
1079
|
+
const existing = this.#batches.get(group);
|
|
1080
|
+
if (existing !== undefined && existing.capacity >= group.memberCount) return existing;
|
|
1081
|
+
const capacity = Math.max(BATCH_MIN_SLOTS, Math.ceil(group.memberCount * BATCH_GROWTH));
|
|
1082
|
+
const first = group.members[0] as Mesh;
|
|
1083
|
+
if (existing !== undefined) this.#disposeBatch(existing);
|
|
1084
|
+
return this.#createBatch(group, first, capacity);
|
|
1085
|
+
}
|
|
1086
|
+
|
|
1087
|
+
#createBatch(group: IProjectionBatchGroup, first: Mesh, capacity: number): IBatch | undefined {
|
|
1088
|
+
const startedAt = globalThis.performance?.now() ?? 0;
|
|
1089
|
+
const uniform = (group as Partial<IProjectionUniformGroup>).uniform === true;
|
|
1090
|
+
// A uniform group stands for many materials, so it cannot draw any of them: it draws a clone the
|
|
1091
|
+
// mirror owns, identical to the group's representative except that its base colour is white and
|
|
1092
|
+
// each instance carries its own. A clone rather than the representative because the
|
|
1093
|
+
// representative is the game's, and a recolour of it must not reach the shared draw — and
|
|
1094
|
+
// because the game's instance is still what 64 cubes hold, and one draw may not have 64 owners.
|
|
1095
|
+
const material = uniform
|
|
1096
|
+
? whiteClone(first.material as Material)
|
|
1097
|
+
: (first.material as Material);
|
|
1098
|
+
let mesh: InstancedMesh;
|
|
1099
|
+
try {
|
|
1100
|
+
mesh = new InstancedMesh(first.geometry, material, capacity);
|
|
1101
|
+
} catch {
|
|
1102
|
+
return undefined;
|
|
1103
|
+
}
|
|
1104
|
+
// Every slot starts collapsed. A slot that is allocated but not yet written would otherwise
|
|
1105
|
+
// draw the geometry at the origin for one frame — a prop flashing at world zero on the frame
|
|
1106
|
+
// the batch grows.
|
|
1107
|
+
for (let slot = 0; slot < capacity; slot += 1) mesh.setMatrixAt(slot, ZERO_MATRIX);
|
|
1108
|
+
mesh.instanceMatrix.needsUpdate = true;
|
|
1109
|
+
// Allocates the buffer three fills with the identity, so only the slots a member actually claims
|
|
1110
|
+
// are ever written. Seeded from the clone's own colour, which is that identity: this is three's
|
|
1111
|
+
// allocation path, not a private buffer the renderer would not know to bind.
|
|
1112
|
+
if (uniform) mesh.setColorAt(0, (material as Material & { color: Color }).color);
|
|
1113
|
+
// The batch spans wherever its instances are, so a bounding test on the whole thing can only
|
|
1114
|
+
// ever answer "visible" and is pure cost.
|
|
1115
|
+
mesh.frustumCulled = false;
|
|
1116
|
+
// Carried from the sources rather than defaulted. The batch is one object to the renderer, so
|
|
1117
|
+
// these are the batch's, and every mesh in it agreed on them — that is what the group means.
|
|
1118
|
+
mesh.castShadow = first.castShadow;
|
|
1119
|
+
mesh.receiveShadow = first.receiveShadow;
|
|
1120
|
+
mesh.layers.mask = first.layers.mask;
|
|
1121
|
+
const batch: IBatch = {
|
|
1122
|
+
mesh,
|
|
1123
|
+
group,
|
|
1124
|
+
geometry: first.geometry,
|
|
1125
|
+
material,
|
|
1126
|
+
uniform,
|
|
1127
|
+
instances: new Map(),
|
|
1128
|
+
free: [],
|
|
1129
|
+
used: 0,
|
|
1130
|
+
capacity,
|
|
1131
|
+
dirty: false,
|
|
1132
|
+
colorsDirty: false,
|
|
1133
|
+
};
|
|
1134
|
+
this.#batches.set(group, batch);
|
|
1135
|
+
this.scene.add(mesh);
|
|
1136
|
+
this.#compileMs += (globalThis.performance?.now() ?? 0) - startedAt;
|
|
1137
|
+
return batch;
|
|
1138
|
+
}
|
|
1139
|
+
|
|
1140
|
+
/**
|
|
1141
|
+
* The batch for one material group, rebuilt whenever the group's geometry set or size outgrows it.
|
|
1142
|
+
*
|
|
1143
|
+
* `BatchedMesh` rather than a second instancing pass, and that is the whole point of the lane:
|
|
1144
|
+
* it holds *many geometries* under *one material*, which is what a town of unique buildings over
|
|
1145
|
+
* shared surfaces needs and what an `InstancedMesh` cannot hold. On three's WebGPU backend the
|
|
1146
|
+
* batch is walked as one render object — one pipeline and bind-group setup, one sort entry, no
|
|
1147
|
+
* per-source matrix pass — with a `drawIndexed` per packed sub-geometry inside it. The draw-count
|
|
1148
|
+
* win is counted from the scene the renderer walks, which is what `resultDrawCandidates` has
|
|
1149
|
+
* always measured.
|
|
1150
|
+
*
|
|
1151
|
+
* Unlike the instanced lane, the packed copies are obligations: budgets are summed from every
|
|
1152
|
+
* distinct geometry before construction so nothing overflows mid-build, and the scan's stream
|
|
1153
|
+
* watch demotes any geometry whose versions move — so a copy never outlives the data it was made
|
|
1154
|
+
* from by even one frame.
|
|
1155
|
+
*/
|
|
1156
|
+
#ensureBatched(group: IProjectionMaterialGroup): IBatched | undefined {
|
|
1157
|
+
const startedAt = globalThis.performance?.now() ?? 0;
|
|
1158
|
+
const existing = this.#materialBatches.get(group);
|
|
1159
|
+
if (
|
|
1160
|
+
existing !== undefined &&
|
|
1161
|
+
existing.builtRevision === group.revision &&
|
|
1162
|
+
existing.capacity >= group.memberCount
|
|
1163
|
+
) {
|
|
1164
|
+
return existing;
|
|
1165
|
+
}
|
|
1166
|
+
if (existing !== undefined) this.#disposeBatched(existing);
|
|
1167
|
+
const capacity = Math.max(BATCH_MIN_SLOTS, Math.ceil(group.memberCount * BATCH_GROWTH));
|
|
1168
|
+
// Sized from the whole group before anything is built; an overflow throw mid-build would
|
|
1169
|
+
// otherwise leave a half-packed batch to dispose around.
|
|
1170
|
+
let vertexBudget = 0;
|
|
1171
|
+
let indexBudget = 0;
|
|
1172
|
+
for (const geometry of group.geometries.keys()) {
|
|
1173
|
+
const position = geometry.getAttribute("position");
|
|
1174
|
+
const vertices = position === undefined ? 0 : position.count;
|
|
1175
|
+
vertexBudget += vertices;
|
|
1176
|
+
const index = geometry.getIndex();
|
|
1177
|
+
indexBudget += index === null ? vertices : index.count;
|
|
1178
|
+
}
|
|
1179
|
+
const reference = group.members[0] as Mesh;
|
|
1180
|
+
const indexed = reference.geometry.getIndex() !== null;
|
|
1181
|
+
let mesh: BatchedMesh;
|
|
1182
|
+
try {
|
|
1183
|
+
mesh = new BatchedMesh(
|
|
1184
|
+
capacity,
|
|
1185
|
+
Math.ceil(vertexBudget * BATCH_GROWTH),
|
|
1186
|
+
indexed ? Math.ceil(indexBudget * BATCH_GROWTH) : 0,
|
|
1187
|
+
group.material,
|
|
1188
|
+
);
|
|
1189
|
+
} catch {
|
|
1190
|
+
return undefined;
|
|
1191
|
+
}
|
|
1192
|
+
// A source with frustumCulled=false may have shader-displaced vertices outside its authored
|
|
1193
|
+
// bounds. Keep that member in a batch that never applies BatchedMesh's bound-based culling;
|
|
1194
|
+
// the planner makes the flag uniform for every member in this batch.
|
|
1195
|
+
mesh.perObjectFrustumCulled = PER_OBJECT_FRUSTUM_CULLED && group.frustumCulled;
|
|
1196
|
+
mesh.sortObjects = SORT_BATCH_OBJECTS;
|
|
1197
|
+
mesh.frustumCulled = false;
|
|
1198
|
+
if (this.#velocityEnabled) {
|
|
1199
|
+
ensureBatchedMeshVelocity(mesh);
|
|
1200
|
+
}
|
|
1201
|
+
// Carried from the sources, exactly as the instanced lane carries them: every member agreed,
|
|
1202
|
+
// because the flags are part of what keyed the group.
|
|
1203
|
+
mesh.castShadow = reference.castShadow;
|
|
1204
|
+
mesh.receiveShadow = reference.receiveShadow;
|
|
1205
|
+
mesh.layers.mask = reference.layers.mask;
|
|
1206
|
+
const batch: IBatched = {
|
|
1207
|
+
mesh,
|
|
1208
|
+
group,
|
|
1209
|
+
material: group.material,
|
|
1210
|
+
geometries: new Map(),
|
|
1211
|
+
instances: new Map(),
|
|
1212
|
+
free: [],
|
|
1213
|
+
used: 0,
|
|
1214
|
+
capacity,
|
|
1215
|
+
builtRevision: group.revision,
|
|
1216
|
+
};
|
|
1217
|
+
try {
|
|
1218
|
+
for (const geometry of group.geometries.keys()) {
|
|
1219
|
+
batch.geometries.set(geometry, mesh.addGeometry(geometry));
|
|
1220
|
+
}
|
|
1221
|
+
} catch {
|
|
1222
|
+
mesh.dispose();
|
|
1223
|
+
return undefined;
|
|
1224
|
+
}
|
|
1225
|
+
this.#materialBatches.set(group, batch);
|
|
1226
|
+
this.scene.add(mesh);
|
|
1227
|
+
this.#compileMs += (globalThis.performance?.now() ?? 0) - startedAt;
|
|
1228
|
+
return batch;
|
|
1229
|
+
}
|
|
1230
|
+
|
|
1231
|
+
/**
|
|
1232
|
+
* Puts an eligible mesh into its material-keyed batch and keeps it there, in step with its
|
|
1233
|
+
* source. Slot bookkeeping is the instanced lane's exactly — allocate once, then per-frame
|
|
1234
|
+
* matrix and visibility compares — with `setVisibleAt` doing natively what a collapsed matrix
|
|
1235
|
+
* does on the other lane.
|
|
1236
|
+
*/
|
|
1237
|
+
#syncBatchedMaterial(target: IBatched, mesh: Mesh): boolean {
|
|
1238
|
+
const previous = this.#state.get(mesh);
|
|
1239
|
+
if (previous !== undefined && previous.batch !== target) this.#release(mesh);
|
|
1240
|
+
this.#releaseProxy(mesh);
|
|
1241
|
+
|
|
1242
|
+
let slot = target.instances.get(mesh);
|
|
1243
|
+
const newSlot = slot === undefined;
|
|
1244
|
+
if (slot === undefined) {
|
|
1245
|
+
if (target.used >= target.capacity) return false;
|
|
1246
|
+
const geometryId = target.geometries.get(mesh.geometry);
|
|
1247
|
+
// A geometry that joined the group after this batch was built cannot be packed into it
|
|
1248
|
+
// here; the revision bump routes the whole group through a rebuild next frame.
|
|
1249
|
+
if (geometryId === undefined) return false;
|
|
1250
|
+
try {
|
|
1251
|
+
slot = target.mesh.addInstance(geometryId);
|
|
1252
|
+
} catch {
|
|
1253
|
+
return false;
|
|
1254
|
+
}
|
|
1255
|
+
target.used += 1;
|
|
1256
|
+
target.instances.set(mesh, slot);
|
|
1257
|
+
this.#state.set(mesh, {
|
|
1258
|
+
// Deliberately unequal to anything real, so the first reconcile below writes the matrix
|
|
1259
|
+
// and the visibility rather than assuming the new slot already carries them.
|
|
1260
|
+
matrixWorld: new Matrix4().multiplyScalar(0),
|
|
1261
|
+
visible: !mesh.visible,
|
|
1262
|
+
geometry: mesh.geometry,
|
|
1263
|
+
material: mesh.material,
|
|
1264
|
+
batch: target,
|
|
1265
|
+
red: Number.NaN,
|
|
1266
|
+
green: Number.NaN,
|
|
1267
|
+
blue: Number.NaN,
|
|
1268
|
+
});
|
|
1269
|
+
}
|
|
1270
|
+
|
|
1271
|
+
const state = this.#state.get(mesh) as ISourceState;
|
|
1272
|
+
const visible = this.#visibleInWorld(mesh);
|
|
1273
|
+
const matrixChanged = !state.matrixWorld.equals(mesh.matrixWorld);
|
|
1274
|
+
if (visible !== state.visible || matrixChanged) {
|
|
1275
|
+
if (this.#velocityEnabled) {
|
|
1276
|
+
const previousMatrix =
|
|
1277
|
+
newSlot || (!state.visible && visible) ? mesh.matrixWorld : state.matrixWorld;
|
|
1278
|
+
setBatchedMeshMatrixWithVelocity(target.mesh, slot, mesh.matrixWorld, previousMatrix);
|
|
1279
|
+
} else target.mesh.setMatrixAt(slot, mesh.matrixWorld);
|
|
1280
|
+
state.matrixWorld.copy(mesh.matrixWorld);
|
|
1281
|
+
state.visible = visible;
|
|
1282
|
+
target.mesh.setVisibleAt(slot, visible);
|
|
1283
|
+
} else if (this.#velocityEnabled) {
|
|
1284
|
+
const previousMatrix =
|
|
1285
|
+
newSlot || (!state.visible && visible) ? mesh.matrixWorld : state.matrixWorld;
|
|
1286
|
+
setBatchedMeshPreviousMatrix(target.mesh, slot, previousMatrix);
|
|
1287
|
+
}
|
|
1288
|
+
state.geometry = mesh.geometry;
|
|
1289
|
+
state.material = mesh.material;
|
|
1290
|
+
state.batch = target;
|
|
1291
|
+
return true;
|
|
1292
|
+
}
|
|
1293
|
+
|
|
1294
|
+
/** Removes a batch from the mirror and releases the buffers it owns. */
|
|
1295
|
+
#disposeBatch(batch: IBatch): void {
|
|
1296
|
+
this.scene.remove(batch.mesh);
|
|
1297
|
+
// The instance matrices are the batch's own; the geometry and material are the game's and are
|
|
1298
|
+
// deliberately left alone — unless this is a uniform draw, where the material is the mirror's
|
|
1299
|
+
// own clone and nobody else's.
|
|
1300
|
+
batch.mesh.dispose();
|
|
1301
|
+
if (batch.uniform) batch.material.dispose();
|
|
1302
|
+
for (const object of batch.instances.keys()) this.#state.delete(object);
|
|
1303
|
+
this.#batches.delete(batch.group);
|
|
1304
|
+
}
|
|
1305
|
+
|
|
1306
|
+
/**
|
|
1307
|
+
* Removes a material-keyed batch from the mirror.
|
|
1308
|
+
*
|
|
1309
|
+
* `BatchedMesh.dispose()` releases the packed vertex/index copies and the instance textures the
|
|
1310
|
+
* batch owns; the source geometries were only read from, never adopted, and stay the game's.
|
|
1311
|
+
*/
|
|
1312
|
+
#disposeBatched(batch: IBatched): void {
|
|
1313
|
+
this.scene.remove(batch.mesh);
|
|
1314
|
+
if (this.#velocityEnabled) disposeBatchedMeshVelocity(batch.mesh);
|
|
1315
|
+
batch.mesh.dispose();
|
|
1316
|
+
for (const object of batch.instances.keys()) this.#state.delete(object);
|
|
1317
|
+
this.#materialBatches.delete(batch.group);
|
|
1318
|
+
}
|
|
1319
|
+
|
|
1320
|
+
/**
|
|
1321
|
+
* Keeps an exact-lane stand-in in step with its source.
|
|
1322
|
+
*
|
|
1323
|
+
* The proxy shares the source's geometry and material by reference — it is the same buffer and
|
|
1324
|
+
* the same material instance, so a game recolouring the original recolours what draws — and
|
|
1325
|
+
* carries the composed world matrix rather than a hierarchy, because the hierarchy above it is
|
|
1326
|
+
* in the authored scene where it belongs.
|
|
1327
|
+
*/
|
|
1328
|
+
#syncProxy(object: Object3D): void {
|
|
1329
|
+
let proxy = this.#proxies.get(object);
|
|
1330
|
+
let fresh = false;
|
|
1331
|
+
if (proxy === undefined) {
|
|
1332
|
+
// `Object3D.prototype.clone` would deep-copy children the mirror does not want; a shallow
|
|
1333
|
+
// stand-in of the same class is what an exact draw needs.
|
|
1334
|
+
proxy = shallowProxy(object);
|
|
1335
|
+
proxy.matrixAutoUpdate = false;
|
|
1336
|
+
this.#proxies.set(object, proxy);
|
|
1337
|
+
fresh = true;
|
|
1338
|
+
// An `LOD` picks one of its levels by distance every frame, and it does that on itself. Its
|
|
1339
|
+
// levels therefore have to hang off the stand-in, or nothing selects one and the mirror
|
|
1340
|
+
// draws whichever rung happened to be visible when it was built.
|
|
1341
|
+
this.#buildLevels(object, proxy);
|
|
1342
|
+
}
|
|
1343
|
+
const source = object as Mesh;
|
|
1344
|
+
const target = proxy as Mesh;
|
|
1345
|
+
target.geometry = source.geometry;
|
|
1346
|
+
target.material = source.material;
|
|
1347
|
+
copySpecializedState(object, proxy);
|
|
1348
|
+
// Written into the *local* matrix, not `matrixWorld`, and this is not a detail.
|
|
1349
|
+
//
|
|
1350
|
+
// The renderer calls `updateMatrixWorld()` on whatever scene it is handed. A `Scene` composes
|
|
1351
|
+
// its own matrix every frame, which sets `matrixWorldNeedsUpdate`, which forces every child to
|
|
1352
|
+
// recompute `matrixWorld` from its local matrix — so anything written straight into
|
|
1353
|
+
// `matrixWorld` is overwritten before a single triangle is drawn, and every proxy in the mirror
|
|
1354
|
+
// renders at the world origin. Writing the local matrix instead survives that recomputation,
|
|
1355
|
+
// because the mirror's root is an identity transform and `identity × matrix` is the world
|
|
1356
|
+
// matrix the source had.
|
|
1357
|
+
target.matrix.copy(object.matrixWorld);
|
|
1358
|
+
target.visible = this.#visibleInWorld(object);
|
|
1359
|
+
target.renderOrder = object.renderOrder;
|
|
1360
|
+
target.castShadow = object.castShadow;
|
|
1361
|
+
target.receiveShadow = object.receiveShadow;
|
|
1362
|
+
target.frustumCulled = object.frustumCulled;
|
|
1363
|
+
target.layers.mask = object.layers.mask;
|
|
1364
|
+
// Added only once it is fully populated, never before.
|
|
1365
|
+
//
|
|
1366
|
+
// A `SkinnedMesh` built by its constructor has no `skeleton` until one is assigned, and
|
|
1367
|
+
// three.js reads `skeleton.bones.length` while it compiles the shader for that object. A
|
|
1368
|
+
// stand-in that is visible to the renderer for even one frame between construction and
|
|
1369
|
+
// assignment throws there, per frame, for as long as the material stays uncompiled — which is
|
|
1370
|
+
// a torrent of console errors and no drawn character.
|
|
1371
|
+
if (fresh) this.scene.add(proxy);
|
|
1372
|
+
}
|
|
1373
|
+
|
|
1374
|
+
/**
|
|
1375
|
+
* Releases one source's instance without disturbing the rest of its batch.
|
|
1376
|
+
*
|
|
1377
|
+
* The batch is retained on the source state rather than found by searching every batch. Searching
|
|
1378
|
+
* is what makes a lane change cost the number of batches in the scene, and lane changes happen
|
|
1379
|
+
* per object per frame.
|
|
1380
|
+
*/
|
|
1381
|
+
#release(object: Object3D): void {
|
|
1382
|
+
const state = this.#state.get(object);
|
|
1383
|
+
const batch = state === undefined ? undefined : state.batch;
|
|
1384
|
+
if (batch instanceof SkinnedBatch) {
|
|
1385
|
+
batch.release(object);
|
|
1386
|
+
this.#state.delete(object);
|
|
1387
|
+
return;
|
|
1388
|
+
}
|
|
1389
|
+
const slot = batch?.instances.get(object);
|
|
1390
|
+
if (batch !== undefined && slot !== undefined) {
|
|
1391
|
+
// Hidden or collapsed before the slot is handed back, so a freed slot draws nothing until
|
|
1392
|
+
// something else claims it. Reusing slots rather than rebuilding the batch is what keeps a
|
|
1393
|
+
// level that streams objects in and out from rebuilding its draws every time it does.
|
|
1394
|
+
if ((batch as IBatch).mesh.isInstancedMesh === true) {
|
|
1395
|
+
if (slot >= 0) {
|
|
1396
|
+
(batch as IBatch).mesh.setMatrixAt(slot, ZERO_MATRIX);
|
|
1397
|
+
(batch as IBatch).mesh.instanceMatrix.needsUpdate = true;
|
|
1398
|
+
}
|
|
1399
|
+
} else {
|
|
1400
|
+
(batch as IBatched).mesh.setVisibleAt(slot, false);
|
|
1401
|
+
}
|
|
1402
|
+
batch.instances.delete(object);
|
|
1403
|
+
if (slot >= 0) batch.free.push(slot);
|
|
1404
|
+
}
|
|
1405
|
+
this.#state.delete(object);
|
|
1406
|
+
}
|
|
1407
|
+
|
|
1408
|
+
/**
|
|
1409
|
+
* Gives an `LOD` stand-in the same levels, at the same distances, as the source.
|
|
1410
|
+
*
|
|
1411
|
+
* `LOD.update()` runs on the container and toggles its children by camera distance, so the
|
|
1412
|
+
* levels must be children of the stand-in for any of that to happen. Each level draws the
|
|
1413
|
+
* source's own geometry and material; only the container is new.
|
|
1414
|
+
*/
|
|
1415
|
+
#buildLevels(object: Object3D, proxy: Object3D): void {
|
|
1416
|
+
if ((object as { isLOD?: boolean }).isLOD !== true) return;
|
|
1417
|
+
const source = object as LOD;
|
|
1418
|
+
const target = proxy as LOD;
|
|
1419
|
+
for (const level of source.levels) {
|
|
1420
|
+
const mesh = shallowProxy(level.object);
|
|
1421
|
+
copySpecializedState(level.object, mesh);
|
|
1422
|
+
mesh.matrix.copy(level.object.matrix);
|
|
1423
|
+
mesh.matrixAutoUpdate = false;
|
|
1424
|
+
target.addLevel(mesh, level.distance, level.hysteresis);
|
|
1425
|
+
}
|
|
1426
|
+
}
|
|
1427
|
+
|
|
1428
|
+
/** Drops an exact-lane stand-in, for a source that no longer needs one. */
|
|
1429
|
+
#releaseProxy(object: Object3D): void {
|
|
1430
|
+
const proxy = this.#proxies.get(object);
|
|
1431
|
+
if (proxy === undefined) return;
|
|
1432
|
+
this.scene.remove(proxy);
|
|
1433
|
+
this.#proxies.delete(object);
|
|
1434
|
+
}
|
|
1435
|
+
|
|
1436
|
+
#clearExactScratch(): void {
|
|
1437
|
+
for (let index = 0; index < this.#exactLaneCount; index += 1) {
|
|
1438
|
+
const entry = this.#exactLane[index] as IProjectionExactEntry;
|
|
1439
|
+
entry.object = undefined;
|
|
1440
|
+
}
|
|
1441
|
+
for (let index = 0; index < this.#extraExactPool.length; index += 1) {
|
|
1442
|
+
const entry = this.#extraExactPool[index] as IProjectionExactEntry;
|
|
1443
|
+
entry.object = undefined;
|
|
1444
|
+
}
|
|
1445
|
+
this.#exactLaneCount = 0;
|
|
1446
|
+
this.#extraExactCount = 0;
|
|
1447
|
+
}
|
|
1448
|
+
|
|
1449
|
+
/** Tears the mirror down, leaving the authored scene untouched, as it has been throughout. */
|
|
1450
|
+
releaseAll(): void {
|
|
1451
|
+
for (const batch of this.#batches.values()) {
|
|
1452
|
+
this.scene.remove(batch.mesh);
|
|
1453
|
+
batch.mesh.dispose();
|
|
1454
|
+
if (batch.uniform) batch.material.dispose();
|
|
1455
|
+
}
|
|
1456
|
+
this.#batches.clear();
|
|
1457
|
+
for (const batch of this.#materialBatches.values()) {
|
|
1458
|
+
this.scene.remove(batch.mesh);
|
|
1459
|
+
if (this.#velocityEnabled) disposeBatchedMeshVelocity(batch.mesh);
|
|
1460
|
+
batch.mesh.dispose();
|
|
1461
|
+
}
|
|
1462
|
+
this.#materialBatches.clear();
|
|
1463
|
+
for (const batch of this.#skinnedBatches.values()) batch.dispose();
|
|
1464
|
+
this.#skinnedBatches.clear();
|
|
1465
|
+
for (const proxy of this.#proxies.values()) this.scene.remove(proxy);
|
|
1466
|
+
this.#proxies.clear();
|
|
1467
|
+
for (const proxy of this.#lightProxies.values()) this.scene.remove(proxy);
|
|
1468
|
+
this.#lightProxies.clear();
|
|
1469
|
+
for (const light of this.#lightShadowAutoUpdate.keys()) this.#restoreLightShadow(light);
|
|
1470
|
+
this.#state.clear();
|
|
1471
|
+
this.#exact.clear();
|
|
1472
|
+
this.#clearExactScratch();
|
|
1473
|
+
this.#projectedObjects = 0;
|
|
1474
|
+
}
|
|
1475
|
+
|
|
1476
|
+
/**
|
|
1477
|
+
* What the mirror currently holds for one source object, or `undefined` if it holds nothing.
|
|
1478
|
+
*
|
|
1479
|
+
* Bounded diagnostics, for the load test and the unit tests: it answers "is this object being
|
|
1480
|
+
* drawn, on which lane, and with what transform and visibility" without exposing the batches or
|
|
1481
|
+
* the reconciliation state. Games never call this — there is no optimizer API in generated
|
|
1482
|
+
* source, and this class is not part of the package's public surface — but a benchmark that
|
|
1483
|
+
* cannot ask what the renderer was given can only report intent, and intent is not evidence.
|
|
1484
|
+
*/
|
|
1485
|
+
inspect(
|
|
1486
|
+
object: Object3D,
|
|
1487
|
+
): { lane: "batched" | "exact"; matrixWorld: Matrix4; visible: boolean } | undefined {
|
|
1488
|
+
const proxy = this.#proxies.get(object);
|
|
1489
|
+
if (proxy !== undefined) {
|
|
1490
|
+
return {
|
|
1491
|
+
lane: "exact",
|
|
1492
|
+
matrixWorld: new Matrix4().copy(proxy.matrix),
|
|
1493
|
+
visible: proxy.visible,
|
|
1494
|
+
};
|
|
1495
|
+
}
|
|
1496
|
+
const state = this.#state.get(object);
|
|
1497
|
+
if (state === undefined) return undefined;
|
|
1498
|
+
const batch = state.batch;
|
|
1499
|
+
const slot = batch?.instances.get(object);
|
|
1500
|
+
if (batch === undefined || slot === undefined) return undefined;
|
|
1501
|
+
const matrixWorld = new Matrix4();
|
|
1502
|
+
// Both lanes answer the same way; which primitive backs the batch is not the caller's business.
|
|
1503
|
+
if (batch instanceof SkinnedBatch) {
|
|
1504
|
+
matrixWorld.copy(state.matrixWorld);
|
|
1505
|
+
} else if ((batch as IBatch).mesh.isInstancedMesh === true && slot < 0) {
|
|
1506
|
+
matrixWorld.copy(state.matrixWorld);
|
|
1507
|
+
} else {
|
|
1508
|
+
batch.mesh.getMatrixAt(slot, matrixWorld);
|
|
1509
|
+
}
|
|
1510
|
+
return { lane: "batched", matrixWorld, visible: state.visible };
|
|
1511
|
+
}
|
|
1512
|
+
|
|
1513
|
+
/** True when some batch in the mirror draws with this exact material instance. */
|
|
1514
|
+
drawsWith(material: Material): boolean {
|
|
1515
|
+
for (const batch of this.#batches.values()) {
|
|
1516
|
+
if (batch.material === material) return true;
|
|
1517
|
+
}
|
|
1518
|
+
for (const batch of this.#materialBatches.values()) {
|
|
1519
|
+
if (batch.material === material) return true;
|
|
1520
|
+
}
|
|
1521
|
+
for (const batch of this.#skinnedBatches.values()) {
|
|
1522
|
+
if (batch.sourceMaterial === material) return true;
|
|
1523
|
+
}
|
|
1524
|
+
for (const proxy of this.#proxies.values()) {
|
|
1525
|
+
if ((proxy as Mesh).material === material) return true;
|
|
1526
|
+
}
|
|
1527
|
+
return false;
|
|
1528
|
+
}
|
|
1529
|
+
}
|