@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,1258 @@
|
|
|
1
|
+
import type {
|
|
2
|
+
BufferAttribute,
|
|
3
|
+
BufferGeometry,
|
|
4
|
+
InterleavedBufferAttribute,
|
|
5
|
+
Light,
|
|
6
|
+
Material,
|
|
7
|
+
Mesh,
|
|
8
|
+
Object3D,
|
|
9
|
+
Scene,
|
|
10
|
+
SkinnedMesh,
|
|
11
|
+
} from "three";
|
|
12
|
+
|
|
13
|
+
import { isEngineRenderHook } from "./engine-render-hook.js";
|
|
14
|
+
import { skinnedMaterialBlocked } from "./projection-skinned.js";
|
|
15
|
+
import { uniformSignatureOf } from "./projection-uniform.js";
|
|
16
|
+
import type { ProjectionExactReason, ProjectionReasonCode } from "./renderProjection.js";
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* The scan-and-plan seam of the render projection (P2-3).
|
|
20
|
+
*
|
|
21
|
+
* Reading the authored scene and deciding what the mirror should do does not touch the mirror or
|
|
22
|
+
* allocate a buffer. The scan owns one caller-provided workspace: active counts are reset and
|
|
23
|
+
* source slots are overwritten in place, while each backing array keeps its high-water length. The
|
|
24
|
+
* seen index advances by generation, and the returned plan is consumed before the next scan. Keeping
|
|
25
|
+
* the decision here means the kill-switch ratio, the mesh floor and the exact-lane classification
|
|
26
|
+
* are testable without a mirror at all.
|
|
27
|
+
*/
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Fewer members than this and a group is not worth batching.
|
|
31
|
+
*
|
|
32
|
+
* An instanced draw of one object is one draw, exactly like the object was, except it also costs a
|
|
33
|
+
* private buffer, a slot table and a per-frame matrix compare. A game whose meshes each carry their
|
|
34
|
+
* own geometry — which is most games that build geometry procedurally, and every game that has
|
|
35
|
+
* already merged its own scene — produces nothing but one-member groups, so batching it converts a
|
|
36
|
+
* cheap scene into an expensive one that draws the same number of times.
|
|
37
|
+
*
|
|
38
|
+
* The same floor applies to a material-keyed batch: folding four distinct geometries under one
|
|
39
|
+
* material saves three draws but costs a packed copy of all of them, and below that the copies
|
|
40
|
+
* cost more than the draws they replace.
|
|
41
|
+
*/
|
|
42
|
+
export const MIN_BATCH_MEMBERS = 4;
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* The projection must be meaningfully better than doing nothing, or it does nothing.
|
|
46
|
+
*
|
|
47
|
+
* This is the rule that was missing, and its absence is the whole of the defect it was added for: a
|
|
48
|
+
* real game that had already merged its own scene from 1,698 meshes to 254 was re-expanded into
|
|
49
|
+
* 1,251 single-member instanced draws — the same draw count as the authored scene, plus a rebuild
|
|
50
|
+
* of every batch on the frame that discovered them. The frame never finished and the screen stayed
|
|
51
|
+
* black. Nothing in the design forbade it, because nothing compared the result against the input.
|
|
52
|
+
*
|
|
53
|
+
* Now everything is predicted from the grouping before a single buffer is allocated, and a
|
|
54
|
+
* projection that cannot beat this ratio is abandoned before it costs anything.
|
|
55
|
+
*/
|
|
56
|
+
const WORTHWHILE_DRAW_RATIO = 0.75;
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* How many rigid meshes one skinned rig counts as against the mesh floor, which is priced in rigid
|
|
60
|
+
* draws. Measured 2026-09-25 on tn-web, NVIDIA Turing, shadows on, 300 frames per arm
|
|
61
|
+
* (`scripts/engine-load-test/skinned-crowd.ts`): 512 shadow-casting boxes cost 0.8 ms of CPU a
|
|
62
|
+
* frame and 512 rigs of 32 bones 20.8 ms, so a rig submits about 26 rigid draws' worth. The scenes
|
|
63
|
+
* this admits below the rigid floor were measured faster, not merely equal: 4 rigs beside 100 props
|
|
64
|
+
* went 6.2 -> 3.85 ms a frame and 8 rigs beside 150 props 9.7 -> 6.85 ms (medians of 4 pairs). A
|
|
65
|
+
* scene whose props cannot batch is still declined by the draw-ratio rule above.
|
|
66
|
+
*/
|
|
67
|
+
const SKINNED_FLOOR_WEIGHT = 26;
|
|
68
|
+
|
|
69
|
+
function isMesh(object: Object3D): object is Mesh {
|
|
70
|
+
return (object as Mesh).isMesh === true;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export function isLight(object: Object3D): object is Light {
|
|
74
|
+
return (object as Light).isLight === true;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** True when the object draws something, whether or not this class can batch it. */
|
|
78
|
+
export function isRenderable(object: Object3D): boolean {
|
|
79
|
+
const candidate = object as Mesh & { isSprite?: boolean; isPoints?: boolean; isLine?: boolean };
|
|
80
|
+
return (
|
|
81
|
+
candidate.isMesh === true ||
|
|
82
|
+
candidate.isSprite === true ||
|
|
83
|
+
candidate.isPoints === true ||
|
|
84
|
+
candidate.isLine === true
|
|
85
|
+
);
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
type ProjectionCandidate = Mesh & {
|
|
89
|
+
isInstancedMesh?: boolean;
|
|
90
|
+
isBatchedMesh?: boolean;
|
|
91
|
+
isSkinnedMesh?: boolean;
|
|
92
|
+
isSprite?: boolean;
|
|
93
|
+
isPoints?: boolean;
|
|
94
|
+
isLine?: boolean;
|
|
95
|
+
isLOD?: boolean;
|
|
96
|
+
customDepthMaterial?: unknown;
|
|
97
|
+
customDistanceMaterial?: unknown;
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
function specializedLaneReason(
|
|
101
|
+
object: Object3D,
|
|
102
|
+
candidate: ProjectionCandidate,
|
|
103
|
+
checkLodAncestors: boolean,
|
|
104
|
+
): ProjectionExactReason | undefined {
|
|
105
|
+
if (candidate.isSprite === true) return "sprite";
|
|
106
|
+
if (candidate.isPoints === true || candidate.isLine === true) return "points";
|
|
107
|
+
if (candidate.isInstancedMesh === true || candidate.isBatchedMesh === true) return "instanced";
|
|
108
|
+
if (candidate.isSkinnedMesh === true) return "skinned";
|
|
109
|
+
if (Array.isArray(candidate.material)) return "multiMaterial";
|
|
110
|
+
if (candidate.customDepthMaterial != null || candidate.customDistanceMaterial != null) {
|
|
111
|
+
return "customDepthMaterial";
|
|
112
|
+
}
|
|
113
|
+
if (checkLodAncestors) {
|
|
114
|
+
for (let node: Object3D | null = object; node !== null; node = node.parent) {
|
|
115
|
+
if ((node as { isLOD?: boolean }).isLOD === true) return "lod";
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
return undefined;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
export function hasMorphAttributes(geometry: BufferGeometry): boolean {
|
|
122
|
+
const targets = geometry.morphAttributes as Record<string, readonly unknown[] | undefined>;
|
|
123
|
+
for (const name in targets) {
|
|
124
|
+
// Three's holder is `{}` until a morph target is added. The native engine's holder always names
|
|
125
|
+
// `position` and `normal`, as empty arrays, so a key alone is not a target: count the targets.
|
|
126
|
+
if (Object.hasOwn(targets, name) && (targets[name]?.length ?? 0) > 0) return true;
|
|
127
|
+
}
|
|
128
|
+
return false;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* True when the material already moves its own vertices: `positionNode`, the shadow path's
|
|
133
|
+
* `castShadowPositionNode`, or a `displacementMap`. Read through `Reflect` because a plain
|
|
134
|
+
* `MeshStandardMaterial` has none of them, and they are read as plain properties rather than through
|
|
135
|
+
* `Reflect` because the structure proof asks this of every material in the scene on every frame:
|
|
136
|
+
* `Reflect.get` is a runtime call on a key the engine cannot fold, and the direct read is a load it
|
|
137
|
+
* can.
|
|
138
|
+
*/
|
|
139
|
+
export function displacesVertices(material: Material): boolean {
|
|
140
|
+
const candidate = material as {
|
|
141
|
+
positionNode?: unknown;
|
|
142
|
+
castShadowPositionNode?: unknown;
|
|
143
|
+
displacementMap?: unknown;
|
|
144
|
+
};
|
|
145
|
+
return (
|
|
146
|
+
candidate.positionNode != null ||
|
|
147
|
+
candidate.castShadowPositionNode != null ||
|
|
148
|
+
candidate.displacementMap != null
|
|
149
|
+
);
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
function geometryLaneReason(geometry: BufferGeometry): ProjectionExactReason | undefined {
|
|
153
|
+
if (geometry.getAttribute("position") === undefined) return "unsupportedGeometry";
|
|
154
|
+
// A GPU-driven field's draw count lives in an indirect buffer a compute pass writes, and a batch
|
|
155
|
+
// draws with the count the CPU last believed. Nothing else about the mesh says so — it is an
|
|
156
|
+
// ordinary `Mesh` with an ordinary material — so without this the field is folded in and its
|
|
157
|
+
// survivor count is discarded while the report claims a clean projection. It keeps its own draw.
|
|
158
|
+
if ((geometry as { indirect?: unknown }).indirect != null) return "indirect";
|
|
159
|
+
if (hasMorphAttributes(geometry)) return "morph";
|
|
160
|
+
const range = geometry.drawRange;
|
|
161
|
+
if (range !== undefined && (range.start !== 0 || Number.isFinite(range.count))) {
|
|
162
|
+
return "drawRange";
|
|
163
|
+
}
|
|
164
|
+
return undefined;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Why a skinned mesh cannot join a skinned batch, or `undefined` when it can.
|
|
169
|
+
*
|
|
170
|
+
* The same semantics a batched draw cannot carry as on the other lanes, plus the ones the palette
|
|
171
|
+
* shader cannot: a material that already moves its own vertices, and a geometry without the four
|
|
172
|
+
* weighted bone influences and the normal the palette deforms.
|
|
173
|
+
*/
|
|
174
|
+
function skinnedLaneReason(object: Object3D): ProjectionExactReason | undefined {
|
|
175
|
+
const candidate = object as ProjectionCandidate & SkinnedMesh;
|
|
176
|
+
if (Array.isArray(candidate.material)) return "multiMaterial";
|
|
177
|
+
if (candidate.customDepthMaterial != null || candidate.customDistanceMaterial != null) {
|
|
178
|
+
return "customDepthMaterial";
|
|
179
|
+
}
|
|
180
|
+
const geometry = candidate.geometry;
|
|
181
|
+
if (geometry === undefined) return "unsupportedGeometry";
|
|
182
|
+
const geometryReason = geometryLaneReason(geometry);
|
|
183
|
+
if (geometryReason !== undefined) return geometryReason;
|
|
184
|
+
if ((object.renderOrder ?? 0) !== 0) return "renderOrder";
|
|
185
|
+
const material = candidate.material as Material | undefined;
|
|
186
|
+
if (material === undefined) return "unsupportedGeometry";
|
|
187
|
+
if (material.transparent === true) return "transparent";
|
|
188
|
+
if (
|
|
189
|
+
skinnedMaterialBlocked(material) ||
|
|
190
|
+
candidate.skeleton === undefined ||
|
|
191
|
+
candidate.skeleton.bones.length === 0 ||
|
|
192
|
+
geometry.getAttribute("normal")?.itemSize !== 3 ||
|
|
193
|
+
geometry.getAttribute("skinIndex")?.itemSize !== 4 ||
|
|
194
|
+
geometry.getAttribute("skinWeight")?.itemSize !== 4
|
|
195
|
+
) {
|
|
196
|
+
return "skinned";
|
|
197
|
+
}
|
|
198
|
+
return undefined;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/**
|
|
202
|
+
* Why a renderable cannot join a batch, or `undefined` when it can.
|
|
203
|
+
*
|
|
204
|
+
* Every entry is a semantic a batched draw provably does not carry. They are named individually
|
|
205
|
+
* because a report saying "12 objects were not batched" is not evidence, and §4.3 requires the
|
|
206
|
+
* ineligible set to be enumerated before a low draw count means anything.
|
|
207
|
+
*/
|
|
208
|
+
export function exactLaneReason(object: Object3D): ProjectionExactReason | undefined {
|
|
209
|
+
return laneReasonOf(object, object as ProjectionCandidate, true);
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* The scan-internal lane classification.
|
|
214
|
+
*
|
|
215
|
+
* Identical to `exactLaneReason` minus the LOD ancestor walk, which the scan can skip: the walk
|
|
216
|
+
* classifies each `LOD` on arrival and never descends into one, so no object visited during a
|
|
217
|
+
* scan can have an LOD ancestor, and checking for one is a full parent-chain read per renderable
|
|
218
|
+
* per frame that can never fire.
|
|
219
|
+
*/
|
|
220
|
+
function walkLaneReason(object: Object3D): ProjectionExactReason | undefined {
|
|
221
|
+
return laneReasonOf(object, object as ProjectionCandidate, false);
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
function laneReasonOf(
|
|
225
|
+
object: Object3D,
|
|
226
|
+
candidate: ProjectionCandidate,
|
|
227
|
+
checkLodAncestors: boolean,
|
|
228
|
+
): ProjectionExactReason | undefined {
|
|
229
|
+
const specialized = specializedLaneReason(object, candidate, checkLodAncestors);
|
|
230
|
+
if (specialized !== undefined) return specialized;
|
|
231
|
+
const geometry = candidate.geometry;
|
|
232
|
+
if (geometry === undefined) return "unsupportedGeometry";
|
|
233
|
+
const geometryReason = geometryLaneReason(geometry);
|
|
234
|
+
if (geometryReason !== undefined) return geometryReason;
|
|
235
|
+
// A batch is one draw, so it has one place in the transparency sort. Objects that asked for a
|
|
236
|
+
// specific place keep their own draw and their own place in it.
|
|
237
|
+
if ((object.renderOrder ?? 0) !== 0) return "renderOrder";
|
|
238
|
+
const material = candidate.material as Material | undefined;
|
|
239
|
+
if (material === undefined) return "unsupportedGeometry";
|
|
240
|
+
if (material.transparent === true) return "transparent";
|
|
241
|
+
// A batch is one object with one model matrix, so a displacement written against the object's own
|
|
242
|
+
// is wrong there, or lost. The mesh keeps its own draw and its own matrix; the skinned lane
|
|
243
|
+
// refuses these materials for the same reason (`skinnedMaterialBlocked`).
|
|
244
|
+
if (displacesVertices(material)) return "vertexDisplaced";
|
|
245
|
+
return undefined;
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* True when the object carries a render callback of its own.
|
|
250
|
+
*
|
|
251
|
+
* Three.js hands `onBeforeRender` the object it is about to draw. A proxy would hand it the proxy,
|
|
252
|
+
* and a batch would not call it at all, so a game that hooks a draw gets its own object back or the
|
|
253
|
+
* frame is not projected. There is no third option that is honest, and this is rare enough that
|
|
254
|
+
* whole-scene fallback is the right price.
|
|
255
|
+
*
|
|
256
|
+
* The engine's own borrows are the exception (PRD-458): `WorldCells` marks each prewarm hook as
|
|
257
|
+
* bookkeeping, and a marked callback claims no object, so folding it away loses nothing. A streamed
|
|
258
|
+
* world carries hundreds of them and unmarking them silently disabled the projection on exactly the
|
|
259
|
+
* scenes it exists for.
|
|
260
|
+
*/
|
|
261
|
+
export function hasRenderHook(object: Object3D): boolean {
|
|
262
|
+
return (
|
|
263
|
+
(Object.hasOwn(object, "onBeforeRender") && !isEngineRenderHook(object.onBeforeRender)) ||
|
|
264
|
+
(Object.hasOwn(object, "onAfterRender") && !isEngineRenderHook(object.onAfterRender))
|
|
265
|
+
);
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
/** Why a source cannot share a batch, or the whole classification for one frame. */
|
|
269
|
+
export interface IProjectionExactEntry {
|
|
270
|
+
object: Object3D | undefined;
|
|
271
|
+
reason: ProjectionExactReason;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
export interface IProjectionSeen {
|
|
275
|
+
has(object: Object3D): boolean;
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
interface IProjectionSeenWorkspace extends IProjectionSeen {
|
|
279
|
+
add(object: Object3D): void;
|
|
280
|
+
begin(): void;
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
class ProjectionSeen implements IProjectionSeenWorkspace {
|
|
284
|
+
#generation = 0;
|
|
285
|
+
#generations = new WeakMap<Object3D, number>();
|
|
286
|
+
|
|
287
|
+
begin(): void {
|
|
288
|
+
this.#generation += 1;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
add(object: Object3D): void {
|
|
292
|
+
this.#generations.set(object, this.#generation);
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
has(object: Object3D): boolean {
|
|
296
|
+
return this.#generations.get(object) === this.#generation;
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
/**
|
|
301
|
+
* A reusable identity group for one (geometry, material, flags) combination.
|
|
302
|
+
*/
|
|
303
|
+
export interface IProjectionBatchGroup {
|
|
304
|
+
readonly geometry: BufferGeometry;
|
|
305
|
+
readonly material: Material;
|
|
306
|
+
readonly castShadow: boolean;
|
|
307
|
+
readonly receiveShadow: boolean;
|
|
308
|
+
readonly frustumCulled: boolean;
|
|
309
|
+
readonly layersMask: number;
|
|
310
|
+
/** High-water member storage; only the first `memberCount` slots belong to the current scan. */
|
|
311
|
+
readonly members: Array<Mesh | undefined>;
|
|
312
|
+
memberCount: number;
|
|
313
|
+
activeScan: number;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/**
|
|
317
|
+
* An instanced group whose members' materials are interchangeable except for their base colour.
|
|
318
|
+
*
|
|
319
|
+
* Keyed on (geometry, material signature, flags) rather than material identity, so a scene of
|
|
320
|
+
* per-object material clones that differ only in albedo — the shape a game gets by cloning a
|
|
321
|
+
* material per prop — collapses to one draw. The draw cannot use the game's material instances,
|
|
322
|
+
* because there is one draw and many materials: it carries a clone the mirror owns with the colour
|
|
323
|
+
* removed, and each instance carries its source material's colour. `material` stays the group's
|
|
324
|
+
* representative, which is what every member was equal to.
|
|
325
|
+
*/
|
|
326
|
+
export interface IProjectionUniformGroup extends IProjectionBatchGroup {
|
|
327
|
+
readonly uniform: true;
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
/**
|
|
331
|
+
* A reusable group of meshes that share a material but not a geometry.
|
|
332
|
+
*
|
|
333
|
+
* This is the second grouping the instanced lane cannot express: a `BatchedMesh` holds many
|
|
334
|
+
* distinct geometries under one material, which is the shape of a real town — hundreds of unique
|
|
335
|
+
* buildings over a handful of surface types. Members are meshes whose own (geometry, material,
|
|
336
|
+
* flags) group fell below the member floor, so a mesh that can still instance-batch keeps doing
|
|
337
|
+
* so and never reaches here.
|
|
338
|
+
*
|
|
339
|
+
* Keyed on (material identity, batch flags, attribute signature). The flags include the source
|
|
340
|
+
* frustum-culling choice: a forced-visible mesh cannot share a per-object-culled batch, because
|
|
341
|
+
* three's packed bounds do not know about shader displacement. The signature — attribute names
|
|
342
|
+
* with item sizes, plus index presence — is what three's `BatchedMesh._validateGeometry` refuses
|
|
343
|
+
* to mix, so geometries that disagree about their attribute sets can never land in one batch.
|
|
344
|
+
* It is keyed on material *identity*, never on material value: a plain property write does not
|
|
345
|
+
* bump `material.version`, so a value key could not be invalidated cheaply and siblings would
|
|
346
|
+
* silently draw with a stale representative.
|
|
347
|
+
*/
|
|
348
|
+
export interface IProjectionMaterialGroup {
|
|
349
|
+
readonly material: Material;
|
|
350
|
+
readonly castShadow: boolean;
|
|
351
|
+
readonly receiveShadow: boolean;
|
|
352
|
+
readonly frustumCulled: boolean;
|
|
353
|
+
readonly layersMask: number;
|
|
354
|
+
/** High-water member storage; only the first `memberCount` slots belong to the current scan. */
|
|
355
|
+
readonly members: Array<Mesh | undefined>;
|
|
356
|
+
memberCount: number;
|
|
357
|
+
activeScan: number;
|
|
358
|
+
/**
|
|
359
|
+
* Each distinct geometry with the attribute-version sum it was last seen carrying. A geometry
|
|
360
|
+
* whose sum moves after admission is game-owned live data — its copies inside a packed batch
|
|
361
|
+
* would silently go stale — so it is demoted out of the lane rather than re-copied.
|
|
362
|
+
*/
|
|
363
|
+
readonly geometries: Map<BufferGeometry, { sum: number; scan: number }>;
|
|
364
|
+
/** Bumped whenever the distinct-geometry set changes, so a built batch knows to rebuild. */
|
|
365
|
+
revision: number;
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
/** All scan-owned storage. It never escapes the synchronous reconcile that owns it. */
|
|
369
|
+
export interface IProjectionScanWorkspace {
|
|
370
|
+
readonly seen: IProjectionSeenWorkspace;
|
|
371
|
+
readonly eligible: Array<Mesh | undefined>;
|
|
372
|
+
eligibleCount: number;
|
|
373
|
+
/** Skinned meshes the palette lane can draw, grouped separately from the rigid lanes. */
|
|
374
|
+
readonly skinned: Array<SkinnedMesh | undefined>;
|
|
375
|
+
skinnedCount: number;
|
|
376
|
+
readonly skinnedGroupsByGeometry: WeakMap<
|
|
377
|
+
BufferGeometry,
|
|
378
|
+
WeakMap<Material, Map<number, IProjectionBatchGroup>>
|
|
379
|
+
>;
|
|
380
|
+
readonly activeSkinnedGroups: Array<IProjectionBatchGroup | undefined>;
|
|
381
|
+
activeSkinnedGroupCount: number;
|
|
382
|
+
readonly skinnedGroups: Array<IProjectionBatchGroup | undefined>;
|
|
383
|
+
skinnedGroupCount: number;
|
|
384
|
+
readonly exactLane: IProjectionExactEntry[];
|
|
385
|
+
readonly exactEntryPool: IProjectionExactEntry[];
|
|
386
|
+
exactLaneCount: number;
|
|
387
|
+
readonly lights: Array<Light | undefined>;
|
|
388
|
+
lightCount: number;
|
|
389
|
+
readonly batchGroups: Array<IProjectionBatchGroup | undefined>;
|
|
390
|
+
batchGroupCount: number;
|
|
391
|
+
readonly materialGroups: Array<IProjectionMaterialGroup | undefined>;
|
|
392
|
+
materialGroupCount: number;
|
|
393
|
+
readonly activeMaterialGroups: Array<IProjectionMaterialGroup | undefined>;
|
|
394
|
+
activeMaterialGroupCount: number;
|
|
395
|
+
readonly belowFloor: Array<Mesh | undefined>;
|
|
396
|
+
belowFloorCount: number;
|
|
397
|
+
readonly activeGroups: Array<IProjectionBatchGroup | undefined>;
|
|
398
|
+
activeGroupCount: number;
|
|
399
|
+
readonly walkStack: Array<Object3D | undefined>;
|
|
400
|
+
walkStackCount: number;
|
|
401
|
+
readonly groupsByGeometry: WeakMap<
|
|
402
|
+
BufferGeometry,
|
|
403
|
+
WeakMap<Material, Map<number, IProjectionBatchGroup>>
|
|
404
|
+
>;
|
|
405
|
+
/**
|
|
406
|
+
* Uniform groups, by geometry, then by the material signature, then by the batching flags — a
|
|
407
|
+
* signature is a value, so the geometry key has to be the weak one for the index not to outlive
|
|
408
|
+
* the geometry it describes.
|
|
409
|
+
*/
|
|
410
|
+
readonly uniformGroups: WeakMap<
|
|
411
|
+
BufferGeometry,
|
|
412
|
+
Map<string, Map<number, IProjectionUniformGroup>>
|
|
413
|
+
>;
|
|
414
|
+
readonly activeUniformGroups: Array<IProjectionUniformGroup | undefined>;
|
|
415
|
+
activeUniformGroupCount: number;
|
|
416
|
+
/** The uniform group each mesh was filed under, so nothing files it a second time this scan. */
|
|
417
|
+
readonly uniformOf: WeakMap<Mesh, IProjectionUniformGroup>;
|
|
418
|
+
readonly groupsByMaterial: WeakMap<Material, Map<number, Map<string, IProjectionMaterialGroup>>>;
|
|
419
|
+
/** Attribute signature per geometry, computed once and interned so group lookup stays pointer-cheap. */
|
|
420
|
+
readonly geometrySignatures: WeakMap<BufferGeometry, string>;
|
|
421
|
+
/**
|
|
422
|
+
* Members claimed by a material group that made the batching floor this scan, stamped with the
|
|
423
|
+
* scan that claimed them. Their below-floor geometry groups must not also file them onto the
|
|
424
|
+
* exact lane — a mesh released into a batch and into a proxy in the same frame draws twice.
|
|
425
|
+
*/
|
|
426
|
+
readonly materialClaims: WeakMap<Object3D, number>;
|
|
427
|
+
/**
|
|
428
|
+
* Geometries caught changing after admission to a material group. Their vertex data is
|
|
429
|
+
* game-owned live — the instanced lane references it, a packed copy cannot — so they are barred
|
|
430
|
+
* from the material lane for good and their meshes fall back to instance-or-exact.
|
|
431
|
+
*/
|
|
432
|
+
readonly streamedGeometries: WeakSet<BufferGeometry>;
|
|
433
|
+
scanNumber: number;
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
/** Gives the frame back to the authored scene, naming why. */
|
|
437
|
+
export interface IProjectionDeclinePlan {
|
|
438
|
+
readonly action: "decline";
|
|
439
|
+
readonly reasonCode: ProjectionReasonCode;
|
|
440
|
+
readonly reason: string;
|
|
441
|
+
}
|
|
442
|
+
|
|
443
|
+
/** Everything the apply seam needs to build and maintain this frame's mirror. */
|
|
444
|
+
export interface IProjectionProjectPlan {
|
|
445
|
+
readonly action: "project";
|
|
446
|
+
/** Groups worth batching, sized before anything is built. */
|
|
447
|
+
readonly batchGroups: readonly (IProjectionBatchGroup | undefined)[];
|
|
448
|
+
readonly batchGroupCount: number;
|
|
449
|
+
/** Material-keyed groups worth batching across differing geometries, sized before anything is built. */
|
|
450
|
+
readonly materialGroups: readonly (IProjectionMaterialGroup | undefined)[];
|
|
451
|
+
readonly materialGroupCount: number;
|
|
452
|
+
/** Skinned groups worth one palette draw each; their members share geometry, material and rig size. */
|
|
453
|
+
readonly skinnedGroups: readonly (IProjectionBatchGroup | undefined)[];
|
|
454
|
+
readonly skinnedGroupCount: number;
|
|
455
|
+
/** Group members below the batching floor: released from batches, drawn on the exact lane. */
|
|
456
|
+
readonly belowFloor: readonly (Mesh | undefined)[];
|
|
457
|
+
readonly belowFloorCount: number;
|
|
458
|
+
/** Objects keeping a draw of their own, with the reason each one did. */
|
|
459
|
+
readonly exactLane: readonly IProjectionExactEntry[];
|
|
460
|
+
readonly exactLaneCount: number;
|
|
461
|
+
/** The scene's lights, to be mirrored rather than moved out of the game's graph. */
|
|
462
|
+
readonly lights: readonly (Light | undefined)[];
|
|
463
|
+
readonly lightCount: number;
|
|
464
|
+
/** Every object the walk saw, for the retirement sweep against sources that left the scene. */
|
|
465
|
+
readonly seen: IProjectionSeen;
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
export type IProjectionPlan = IProjectionDeclinePlan | IProjectionProjectPlan;
|
|
469
|
+
|
|
470
|
+
export interface IProjectionScanResult {
|
|
471
|
+
/** Exact-lane entries from the walk alone, before batching decisions add more. */
|
|
472
|
+
readonly exactLane: readonly IProjectionExactEntry[];
|
|
473
|
+
readonly exactLaneCount: number;
|
|
474
|
+
/** Decline without touching the mirror, or build what the plan describes. */
|
|
475
|
+
readonly plan: IProjectionPlan;
|
|
476
|
+
/** Renderables the authored scene holds — what an unoptimized frame would walk and draw. */
|
|
477
|
+
readonly renderables: number;
|
|
478
|
+
readonly seen: IProjectionSeen;
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
export function createProjectionScanWorkspace(): IProjectionScanWorkspace {
|
|
482
|
+
return {
|
|
483
|
+
seen: new ProjectionSeen(),
|
|
484
|
+
eligible: [],
|
|
485
|
+
eligibleCount: 0,
|
|
486
|
+
skinned: [],
|
|
487
|
+
skinnedCount: 0,
|
|
488
|
+
skinnedGroupsByGeometry: new WeakMap(),
|
|
489
|
+
activeSkinnedGroups: [],
|
|
490
|
+
activeSkinnedGroupCount: 0,
|
|
491
|
+
skinnedGroups: [],
|
|
492
|
+
skinnedGroupCount: 0,
|
|
493
|
+
exactLane: [],
|
|
494
|
+
exactEntryPool: [],
|
|
495
|
+
exactLaneCount: 0,
|
|
496
|
+
lights: [],
|
|
497
|
+
lightCount: 0,
|
|
498
|
+
batchGroups: [],
|
|
499
|
+
batchGroupCount: 0,
|
|
500
|
+
materialGroups: [],
|
|
501
|
+
materialGroupCount: 0,
|
|
502
|
+
activeMaterialGroups: [],
|
|
503
|
+
activeMaterialGroupCount: 0,
|
|
504
|
+
belowFloor: [],
|
|
505
|
+
belowFloorCount: 0,
|
|
506
|
+
activeGroups: [],
|
|
507
|
+
activeGroupCount: 0,
|
|
508
|
+
walkStack: [],
|
|
509
|
+
walkStackCount: 0,
|
|
510
|
+
groupsByGeometry: new WeakMap(),
|
|
511
|
+
uniformGroups: new WeakMap(),
|
|
512
|
+
activeUniformGroups: [],
|
|
513
|
+
activeUniformGroupCount: 0,
|
|
514
|
+
uniformOf: new WeakMap(),
|
|
515
|
+
groupsByMaterial: new WeakMap(),
|
|
516
|
+
geometrySignatures: new WeakMap(),
|
|
517
|
+
materialClaims: new WeakMap(),
|
|
518
|
+
streamedGeometries: new WeakSet(),
|
|
519
|
+
scanNumber: 0,
|
|
520
|
+
};
|
|
521
|
+
}
|
|
522
|
+
|
|
523
|
+
/**
|
|
524
|
+
* Releases source references from the reusable scan storage after its plan is consumed.
|
|
525
|
+
*
|
|
526
|
+
* The arrays and identity maps stay reusable at their high-water lengths, but their members are
|
|
527
|
+
* borrowed from the authored scene. Clearing active slots without truncating them avoids backing
|
|
528
|
+
* store churn; keeping those members in an inactive group or pooled exact entry would make a
|
|
529
|
+
* streamed scene retain every mesh it had ever contained.
|
|
530
|
+
*/
|
|
531
|
+
/**
|
|
532
|
+
* Releases one active material group's members and stale geometry baselines.
|
|
533
|
+
*
|
|
534
|
+
* A geometry that no longer has a member this scan has stopped participating; its baseline is
|
|
535
|
+
* dropped so the watch does not sum versions forever for data nothing draws. The entry is
|
|
536
|
+
* re-established with a fresh baseline if the geometry comes back, which is correct — the batch
|
|
537
|
+
* is built from whatever the vertex data carries at that point.
|
|
538
|
+
*/
|
|
539
|
+
function releaseActiveMaterialGroup(
|
|
540
|
+
workspace: IProjectionScanWorkspace,
|
|
541
|
+
group: IProjectionMaterialGroup,
|
|
542
|
+
): void {
|
|
543
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
544
|
+
group.members[member] = undefined;
|
|
545
|
+
}
|
|
546
|
+
group.memberCount = 0;
|
|
547
|
+
for (const [geometry, record] of group.geometries) {
|
|
548
|
+
if (record.scan !== workspace.scanNumber) group.geometries.delete(geometry);
|
|
549
|
+
}
|
|
550
|
+
}
|
|
551
|
+
|
|
552
|
+
/** The skinned lane's share of `releaseProjectionScanWorkspace`. */
|
|
553
|
+
function releaseSkinnedScan(workspace: IProjectionScanWorkspace): void {
|
|
554
|
+
for (let index = 0; index < workspace.skinnedCount; index += 1) {
|
|
555
|
+
workspace.skinned[index] = undefined;
|
|
556
|
+
}
|
|
557
|
+
for (let index = 0; index < workspace.activeSkinnedGroupCount; index += 1) {
|
|
558
|
+
const group = workspace.activeSkinnedGroups[index] as IProjectionBatchGroup;
|
|
559
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
560
|
+
group.members[member] = undefined;
|
|
561
|
+
}
|
|
562
|
+
group.memberCount = 0;
|
|
563
|
+
workspace.activeSkinnedGroups[index] = undefined;
|
|
564
|
+
}
|
|
565
|
+
for (let index = 0; index < workspace.skinnedGroupCount; index += 1) {
|
|
566
|
+
workspace.skinnedGroups[index] = undefined;
|
|
567
|
+
}
|
|
568
|
+
workspace.skinnedCount = 0;
|
|
569
|
+
workspace.activeSkinnedGroupCount = 0;
|
|
570
|
+
workspace.skinnedGroupCount = 0;
|
|
571
|
+
}
|
|
572
|
+
|
|
573
|
+
export function releaseProjectionScanWorkspace(workspace: IProjectionScanWorkspace): void {
|
|
574
|
+
for (let index = 0; index < workspace.exactEntryPool.length; index += 1) {
|
|
575
|
+
const entry = workspace.exactEntryPool[index] as IProjectionExactEntry;
|
|
576
|
+
entry.object = undefined;
|
|
577
|
+
}
|
|
578
|
+
for (let index = 0; index < workspace.activeGroupCount; index += 1) {
|
|
579
|
+
const group = workspace.activeGroups[index] as IProjectionBatchGroup;
|
|
580
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
581
|
+
group.members[member] = undefined;
|
|
582
|
+
}
|
|
583
|
+
group.memberCount = 0;
|
|
584
|
+
workspace.activeGroups[index] = undefined;
|
|
585
|
+
}
|
|
586
|
+
for (let index = 0; index < workspace.activeUniformGroupCount; index += 1) {
|
|
587
|
+
const group = workspace.activeUniformGroups[index] as IProjectionUniformGroup;
|
|
588
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
589
|
+
group.members[member] = undefined;
|
|
590
|
+
}
|
|
591
|
+
group.memberCount = 0;
|
|
592
|
+
workspace.activeUniformGroups[index] = undefined;
|
|
593
|
+
}
|
|
594
|
+
for (let index = 0; index < workspace.activeMaterialGroupCount; index += 1) {
|
|
595
|
+
releaseActiveMaterialGroup(
|
|
596
|
+
workspace,
|
|
597
|
+
workspace.activeMaterialGroups[index] as IProjectionMaterialGroup,
|
|
598
|
+
);
|
|
599
|
+
workspace.activeMaterialGroups[index] = undefined;
|
|
600
|
+
}
|
|
601
|
+
for (let index = 0; index < workspace.eligibleCount; index += 1) {
|
|
602
|
+
workspace.eligible[index] = undefined;
|
|
603
|
+
}
|
|
604
|
+
releaseSkinnedScan(workspace);
|
|
605
|
+
for (let index = 0; index < workspace.exactLaneCount; index += 1) {
|
|
606
|
+
const entry = workspace.exactLane[index] as IProjectionExactEntry;
|
|
607
|
+
entry.object = undefined;
|
|
608
|
+
}
|
|
609
|
+
for (let index = 0; index < workspace.lightCount; index += 1) {
|
|
610
|
+
workspace.lights[index] = undefined;
|
|
611
|
+
}
|
|
612
|
+
for (let index = 0; index < workspace.batchGroupCount; index += 1) {
|
|
613
|
+
workspace.batchGroups[index] = undefined;
|
|
614
|
+
}
|
|
615
|
+
for (let index = 0; index < workspace.materialGroupCount; index += 1) {
|
|
616
|
+
workspace.materialGroups[index] = undefined;
|
|
617
|
+
}
|
|
618
|
+
for (let index = 0; index < workspace.belowFloorCount; index += 1) {
|
|
619
|
+
workspace.belowFloor[index] = undefined;
|
|
620
|
+
}
|
|
621
|
+
for (let index = 0; index < workspace.walkStackCount; index += 1) {
|
|
622
|
+
workspace.walkStack[index] = undefined;
|
|
623
|
+
}
|
|
624
|
+
workspace.eligibleCount = 0;
|
|
625
|
+
workspace.exactLaneCount = 0;
|
|
626
|
+
workspace.lightCount = 0;
|
|
627
|
+
workspace.batchGroupCount = 0;
|
|
628
|
+
workspace.materialGroupCount = 0;
|
|
629
|
+
workspace.activeMaterialGroupCount = 0;
|
|
630
|
+
workspace.belowFloorCount = 0;
|
|
631
|
+
workspace.activeGroupCount = 0;
|
|
632
|
+
workspace.activeUniformGroupCount = 0;
|
|
633
|
+
workspace.walkStackCount = 0;
|
|
634
|
+
}
|
|
635
|
+
|
|
636
|
+
function addExactEntry(
|
|
637
|
+
workspace: IProjectionScanWorkspace,
|
|
638
|
+
object: Object3D,
|
|
639
|
+
reason: ProjectionExactReason,
|
|
640
|
+
): void {
|
|
641
|
+
const index = workspace.exactLaneCount;
|
|
642
|
+
let entry = workspace.exactEntryPool[index];
|
|
643
|
+
if (entry === undefined) {
|
|
644
|
+
entry = { object, reason };
|
|
645
|
+
workspace.exactEntryPool.push(entry);
|
|
646
|
+
} else {
|
|
647
|
+
entry.object = object;
|
|
648
|
+
entry.reason = reason;
|
|
649
|
+
}
|
|
650
|
+
workspace.exactLane[index] = entry;
|
|
651
|
+
workspace.exactLaneCount += 1;
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
function batchFlagsOf(mesh: Mesh): number {
|
|
655
|
+
return (
|
|
656
|
+
(mesh.layers.mask >>> 0) * 8 +
|
|
657
|
+
(mesh.castShadow ? 4 : 0) +
|
|
658
|
+
(mesh.receiveShadow ? 2 : 0) +
|
|
659
|
+
(mesh.frustumCulled ? 1 : 0)
|
|
660
|
+
);
|
|
661
|
+
}
|
|
662
|
+
|
|
663
|
+
function addToBatchGroup(
|
|
664
|
+
workspace: IProjectionScanWorkspace,
|
|
665
|
+
mesh: Mesh,
|
|
666
|
+
scanNumber: number,
|
|
667
|
+
): void {
|
|
668
|
+
const byFlags = flagGroupsOf(workspace.groupsByGeometry, mesh);
|
|
669
|
+
const flags = batchFlagsOf(mesh);
|
|
670
|
+
const group = activeGroupOf(byFlags, flags, mesh, scanNumber);
|
|
671
|
+
if (group.memberCount === 0) {
|
|
672
|
+
workspace.activeGroups[workspace.activeGroupCount] = group;
|
|
673
|
+
workspace.activeGroupCount += 1;
|
|
674
|
+
}
|
|
675
|
+
group.members[group.memberCount] = mesh;
|
|
676
|
+
group.memberCount += 1;
|
|
677
|
+
}
|
|
678
|
+
|
|
679
|
+
/**
|
|
680
|
+
* Files a skinned mesh under (geometry, material, flags, bone count). The bone count is part of
|
|
681
|
+
* the key because it is the palette stride: rigs of different sizes cannot share one shader.
|
|
682
|
+
*/
|
|
683
|
+
function addToSkinnedGroup(
|
|
684
|
+
workspace: IProjectionScanWorkspace,
|
|
685
|
+
mesh: SkinnedMesh,
|
|
686
|
+
scanNumber: number,
|
|
687
|
+
): void {
|
|
688
|
+
const byFlags = flagGroupsOf(workspace.skinnedGroupsByGeometry, mesh);
|
|
689
|
+
// Bone counts stay far below 2^16, so the composite key stays an exact integer.
|
|
690
|
+
const key = batchFlagsOf(mesh) * 65536 + mesh.skeleton.bones.length;
|
|
691
|
+
const group = activeGroupOf(byFlags, key, mesh, scanNumber);
|
|
692
|
+
if (group.memberCount === 0) {
|
|
693
|
+
workspace.activeSkinnedGroups[workspace.activeSkinnedGroupCount] = group;
|
|
694
|
+
workspace.activeSkinnedGroupCount += 1;
|
|
695
|
+
}
|
|
696
|
+
group.members[group.memberCount] = mesh;
|
|
697
|
+
group.memberCount += 1;
|
|
698
|
+
}
|
|
699
|
+
|
|
700
|
+
function flagGroupsOf(
|
|
701
|
+
index: WeakMap<BufferGeometry, WeakMap<Material, Map<number, IProjectionBatchGroup>>>,
|
|
702
|
+
mesh: Mesh,
|
|
703
|
+
): Map<number, IProjectionBatchGroup> {
|
|
704
|
+
const geometry = mesh.geometry;
|
|
705
|
+
const material = mesh.material as Material;
|
|
706
|
+
let byMaterial = index.get(geometry);
|
|
707
|
+
if (byMaterial === undefined) {
|
|
708
|
+
byMaterial = new WeakMap();
|
|
709
|
+
index.set(geometry, byMaterial);
|
|
710
|
+
}
|
|
711
|
+
let byFlags = byMaterial.get(material);
|
|
712
|
+
if (byFlags === undefined) {
|
|
713
|
+
byFlags = new Map();
|
|
714
|
+
byMaterial.set(material, byFlags);
|
|
715
|
+
}
|
|
716
|
+
return byFlags;
|
|
717
|
+
}
|
|
718
|
+
|
|
719
|
+
/** The group for `key`, emptied on its first sighting this scan. */
|
|
720
|
+
function activeGroupOf(
|
|
721
|
+
byFlags: Map<number, IProjectionBatchGroup>,
|
|
722
|
+
key: number,
|
|
723
|
+
mesh: Mesh,
|
|
724
|
+
scanNumber: number,
|
|
725
|
+
): IProjectionBatchGroup {
|
|
726
|
+
const geometry = mesh.geometry;
|
|
727
|
+
const material = mesh.material as Material;
|
|
728
|
+
let group = byFlags.get(key);
|
|
729
|
+
if (group === undefined) {
|
|
730
|
+
group = {
|
|
731
|
+
geometry,
|
|
732
|
+
material,
|
|
733
|
+
castShadow: mesh.castShadow,
|
|
734
|
+
receiveShadow: mesh.receiveShadow,
|
|
735
|
+
frustumCulled: mesh.frustumCulled,
|
|
736
|
+
layersMask: mesh.layers.mask,
|
|
737
|
+
members: [],
|
|
738
|
+
memberCount: 0,
|
|
739
|
+
activeScan: 0,
|
|
740
|
+
};
|
|
741
|
+
byFlags.set(key, group);
|
|
742
|
+
}
|
|
743
|
+
if (group.activeScan !== scanNumber) {
|
|
744
|
+
group.activeScan = scanNumber;
|
|
745
|
+
group.memberCount = 0;
|
|
746
|
+
}
|
|
747
|
+
return group;
|
|
748
|
+
}
|
|
749
|
+
|
|
750
|
+
/**
|
|
751
|
+
* What three's `BatchedMesh._validateGeometry` refuses to mix, as one interned string.
|
|
752
|
+
*
|
|
753
|
+
* Index presence plus every attribute name with its item size and normalization. Cached per
|
|
754
|
+
* geometry, so a steady frame pays one WeakMap lookup; only a geometry's first sighting builds
|
|
755
|
+
* the string. Two geometries that disagree here cannot share a packed batch, so the signature is
|
|
756
|
+
* part of the material-group key rather than a check applied after grouping.
|
|
757
|
+
*/
|
|
758
|
+
function geometrySignatureOf(
|
|
759
|
+
workspace: IProjectionScanWorkspace,
|
|
760
|
+
geometry: BufferGeometry,
|
|
761
|
+
): string {
|
|
762
|
+
const cached = workspace.geometrySignatures.get(geometry);
|
|
763
|
+
if (cached !== undefined) return cached;
|
|
764
|
+
const names = Object.keys(geometry.attributes).sort();
|
|
765
|
+
let signature = geometry.getIndex() === null ? "n" : "i";
|
|
766
|
+
for (let index = 0; index < names.length; index += 1) {
|
|
767
|
+
const name = names[index] as string;
|
|
768
|
+
const attribute = geometry.getAttribute(name);
|
|
769
|
+
if (attribute === undefined) continue;
|
|
770
|
+
signature += ` ${name}:${attribute.itemSize}:${attribute.normalized ? 1 : 0}`;
|
|
771
|
+
}
|
|
772
|
+
workspace.geometrySignatures.set(geometry, signature);
|
|
773
|
+
return signature;
|
|
774
|
+
}
|
|
775
|
+
|
|
776
|
+
/** Versions only ever increase, so an attribute's version is a usable change signal. */
|
|
777
|
+
function attributeVersionOf(attribute: BufferAttribute | InterleavedBufferAttribute): number {
|
|
778
|
+
// An interleaved attribute's version lives on the shared buffer it slices into.
|
|
779
|
+
if ("isInterleavedBufferAttribute" in attribute) return attribute.data.version;
|
|
780
|
+
return attribute.version;
|
|
781
|
+
}
|
|
782
|
+
|
|
783
|
+
/**
|
|
784
|
+
* Sums every attribute version, plus the index's, into one number.
|
|
785
|
+
*
|
|
786
|
+
* Versions only ever increase, so the sum does too: any single `needsUpdate` write moves it. This
|
|
787
|
+
* is how the lane learns that a game streams into vertex data it had admitted — the one thing a
|
|
788
|
+
* packed copy cannot follow that the instanced lane's shared reference can.
|
|
789
|
+
*/
|
|
790
|
+
export function geometryVersionSum(geometry: BufferGeometry): number {
|
|
791
|
+
let sum = 0;
|
|
792
|
+
for (const name in geometry.attributes) {
|
|
793
|
+
if (!Object.hasOwn(geometry.attributes, name)) continue;
|
|
794
|
+
const attribute = geometry.getAttribute(name);
|
|
795
|
+
if (attribute !== undefined) sum += attributeVersionOf(attribute);
|
|
796
|
+
}
|
|
797
|
+
const index = geometry.getIndex();
|
|
798
|
+
return index === null ? sum : sum + attributeVersionOf(index);
|
|
799
|
+
}
|
|
800
|
+
|
|
801
|
+
/**
|
|
802
|
+
* Files a mesh under (geometry, material signature, flags) for a draw that carries the colour
|
|
803
|
+
* per instance.
|
|
804
|
+
*
|
|
805
|
+
* The signature is the material's own readable properties minus its colour, so a mesh whose
|
|
806
|
+
* material is ineligible — transparent, vertex-coloured, a node graph, an unknown class — simply
|
|
807
|
+
* has no signature and never reaches this lane. A material that shares an instance with a twin is
|
|
808
|
+
* still better served by the identity lane, so this runs over the groups that fell below its floor.
|
|
809
|
+
*/
|
|
810
|
+
function addToUniformGroup(
|
|
811
|
+
workspace: IProjectionScanWorkspace,
|
|
812
|
+
mesh: Mesh,
|
|
813
|
+
scanNumber: number,
|
|
814
|
+
): void {
|
|
815
|
+
const geometry = mesh.geometry;
|
|
816
|
+
const material = mesh.material as Material;
|
|
817
|
+
const signature = uniformSignatureOf(material);
|
|
818
|
+
if (signature === undefined) return;
|
|
819
|
+
const flags = batchFlagsOf(mesh);
|
|
820
|
+
let bySignature = workspace.uniformGroups.get(geometry);
|
|
821
|
+
if (bySignature === undefined) {
|
|
822
|
+
bySignature = new Map();
|
|
823
|
+
workspace.uniformGroups.set(geometry, bySignature);
|
|
824
|
+
}
|
|
825
|
+
let byFlags = bySignature.get(signature);
|
|
826
|
+
if (byFlags === undefined) {
|
|
827
|
+
byFlags = new Map();
|
|
828
|
+
bySignature.set(signature, byFlags);
|
|
829
|
+
}
|
|
830
|
+
let group = byFlags.get(flags);
|
|
831
|
+
if (group === undefined) {
|
|
832
|
+
group = {
|
|
833
|
+
geometry,
|
|
834
|
+
material,
|
|
835
|
+
castShadow: mesh.castShadow,
|
|
836
|
+
receiveShadow: mesh.receiveShadow,
|
|
837
|
+
frustumCulled: mesh.frustumCulled,
|
|
838
|
+
layersMask: mesh.layers.mask,
|
|
839
|
+
members: [],
|
|
840
|
+
memberCount: 0,
|
|
841
|
+
activeScan: 0,
|
|
842
|
+
uniform: true,
|
|
843
|
+
};
|
|
844
|
+
byFlags.set(flags, group);
|
|
845
|
+
}
|
|
846
|
+
if (group.activeScan !== scanNumber) {
|
|
847
|
+
group.activeScan = scanNumber;
|
|
848
|
+
group.memberCount = 0;
|
|
849
|
+
workspace.activeUniformGroups[workspace.activeUniformGroupCount] = group;
|
|
850
|
+
workspace.activeUniformGroupCount += 1;
|
|
851
|
+
}
|
|
852
|
+
group.members[group.memberCount] = mesh;
|
|
853
|
+
group.memberCount += 1;
|
|
854
|
+
workspace.uniformOf.set(mesh, group);
|
|
855
|
+
}
|
|
856
|
+
|
|
857
|
+
/** Whether a mesh was claimed by a uniform group that made the member floor this scan. */
|
|
858
|
+
function uniformClaimed(workspace: IProjectionScanWorkspace, mesh: Mesh): boolean {
|
|
859
|
+
const group = workspace.uniformOf.get(mesh);
|
|
860
|
+
return group !== undefined && group.memberCount >= MIN_BATCH_MEMBERS;
|
|
861
|
+
}
|
|
862
|
+
|
|
863
|
+
function addToMaterialGroup(
|
|
864
|
+
workspace: IProjectionScanWorkspace,
|
|
865
|
+
mesh: Mesh,
|
|
866
|
+
scanNumber: number,
|
|
867
|
+
): void {
|
|
868
|
+
const geometry = mesh.geometry;
|
|
869
|
+
// Barred for good: this geometry was caught changing under a built batch once already, and a
|
|
870
|
+
// packed copy would go stale again. The instanced lane still references it live when it has
|
|
871
|
+
// twins; alone it draws on the exact lane.
|
|
872
|
+
if (workspace.streamedGeometries.has(geometry)) return;
|
|
873
|
+
const material = mesh.material as Material;
|
|
874
|
+
const flags = batchFlagsOf(mesh);
|
|
875
|
+
const signature = geometrySignatureOf(workspace, geometry);
|
|
876
|
+
let byFlags = workspace.groupsByMaterial.get(material);
|
|
877
|
+
if (byFlags === undefined) {
|
|
878
|
+
byFlags = new Map();
|
|
879
|
+
workspace.groupsByMaterial.set(material, byFlags);
|
|
880
|
+
}
|
|
881
|
+
let bySignature = byFlags.get(flags);
|
|
882
|
+
if (bySignature === undefined) {
|
|
883
|
+
bySignature = new Map();
|
|
884
|
+
byFlags.set(flags, bySignature);
|
|
885
|
+
}
|
|
886
|
+
let group = bySignature.get(signature);
|
|
887
|
+
if (group === undefined) {
|
|
888
|
+
group = {
|
|
889
|
+
material,
|
|
890
|
+
castShadow: mesh.castShadow,
|
|
891
|
+
receiveShadow: mesh.receiveShadow,
|
|
892
|
+
frustumCulled: mesh.frustumCulled,
|
|
893
|
+
layersMask: mesh.layers.mask,
|
|
894
|
+
members: [],
|
|
895
|
+
memberCount: 0,
|
|
896
|
+
activeScan: 0,
|
|
897
|
+
geometries: new Map(),
|
|
898
|
+
revision: 0,
|
|
899
|
+
};
|
|
900
|
+
bySignature.set(signature, group);
|
|
901
|
+
}
|
|
902
|
+
if (group.activeScan !== scanNumber) {
|
|
903
|
+
group.activeScan = scanNumber;
|
|
904
|
+
group.memberCount = 0;
|
|
905
|
+
workspace.activeMaterialGroups[workspace.activeMaterialGroupCount] = group;
|
|
906
|
+
workspace.activeMaterialGroupCount += 1;
|
|
907
|
+
}
|
|
908
|
+
const record = group.geometries.get(geometry);
|
|
909
|
+
if (record === undefined) {
|
|
910
|
+
group.geometries.set(geometry, { sum: geometryVersionSum(geometry), scan: scanNumber });
|
|
911
|
+
group.revision += 1;
|
|
912
|
+
} else {
|
|
913
|
+
record.scan = scanNumber;
|
|
914
|
+
}
|
|
915
|
+
group.members[group.memberCount] = mesh;
|
|
916
|
+
group.memberCount += 1;
|
|
917
|
+
}
|
|
918
|
+
|
|
919
|
+
/**
|
|
920
|
+
* Compacts one geometry's members out of a material group.
|
|
921
|
+
*
|
|
922
|
+
* They are not pushed anywhere: every member here came from a below-floor geometry group and is
|
|
923
|
+
* still listed in it, so the below-floor sweep hands them to the exact lane exactly once. What
|
|
924
|
+
* this removes them from is the batch they can no longer honestly join.
|
|
925
|
+
*/
|
|
926
|
+
function evictGeometryMembers(group: IProjectionMaterialGroup, geometry: BufferGeometry): void {
|
|
927
|
+
let writeIndex = 0;
|
|
928
|
+
for (let readIndex = 0; readIndex < group.memberCount; readIndex += 1) {
|
|
929
|
+
const member = group.members[readIndex] as Mesh;
|
|
930
|
+
if (member.geometry === geometry) continue;
|
|
931
|
+
group.members[writeIndex] = member;
|
|
932
|
+
writeIndex += 1;
|
|
933
|
+
}
|
|
934
|
+
for (let slot = writeIndex; slot < group.memberCount; slot += 1) {
|
|
935
|
+
group.members[slot] = undefined;
|
|
936
|
+
}
|
|
937
|
+
group.memberCount = writeIndex;
|
|
938
|
+
}
|
|
939
|
+
|
|
940
|
+
/**
|
|
941
|
+
* Watches the vertex data of everything admitted to a material group.
|
|
942
|
+
*
|
|
943
|
+
* Runs after routing, on the same frame the data would be copied: a version-sum move demotes the
|
|
944
|
+
* geometry before this frame's plan is built, so no frame ever renders from a stale copy — the
|
|
945
|
+
* meshes fall to the exact lane with their live references instead. Steady frames compare sums
|
|
946
|
+
* and touch nothing.
|
|
947
|
+
*/
|
|
948
|
+
function watchMaterialGroupGeometries(workspace: IProjectionScanWorkspace): void {
|
|
949
|
+
for (let index = 0; index < workspace.activeMaterialGroupCount; index += 1) {
|
|
950
|
+
const group = workspace.activeMaterialGroups[index] as IProjectionMaterialGroup;
|
|
951
|
+
for (const [geometry, record] of group.geometries) {
|
|
952
|
+
const sum = geometryVersionSum(geometry);
|
|
953
|
+
if (sum === record.sum) continue;
|
|
954
|
+
workspace.streamedGeometries.add(geometry);
|
|
955
|
+
group.geometries.delete(geometry);
|
|
956
|
+
group.revision += 1;
|
|
957
|
+
evictGeometryMembers(group, geometry);
|
|
958
|
+
}
|
|
959
|
+
}
|
|
960
|
+
}
|
|
961
|
+
|
|
962
|
+
interface IProjectionWalkState {
|
|
963
|
+
renderables: number;
|
|
964
|
+
blocked?: { code: ProjectionReasonCode; reason: string };
|
|
965
|
+
}
|
|
966
|
+
|
|
967
|
+
function visitProjectionObject(
|
|
968
|
+
object: Object3D,
|
|
969
|
+
workspace: IProjectionScanWorkspace,
|
|
970
|
+
state: IProjectionWalkState,
|
|
971
|
+
): void {
|
|
972
|
+
// A hook is handed the object being drawn, and neither a batch nor a proxy can hand back the
|
|
973
|
+
// game's own object. The frame goes to the authored scene instead.
|
|
974
|
+
if (state.blocked === undefined && hasRenderHook(object)) {
|
|
975
|
+
state.blocked = {
|
|
976
|
+
code: "renderHook",
|
|
977
|
+
reason: "an object carries its own onBeforeRender/onAfterRender",
|
|
978
|
+
};
|
|
979
|
+
}
|
|
980
|
+
if (isLight(object)) {
|
|
981
|
+
workspace.lights[workspace.lightCount] = object;
|
|
982
|
+
workspace.lightCount += 1;
|
|
983
|
+
return;
|
|
984
|
+
}
|
|
985
|
+
// A BatchedMesh carries private geometry ids, visibility and matrix textures for its sub-draws.
|
|
986
|
+
// The mirror can create its own BatchedMesh for material groups, but it cannot reconstruct an
|
|
987
|
+
// authored one through the shallow exact proxy without losing those live tables. Keep the
|
|
988
|
+
// authored object as the renderer input until a faithful mirror seam exists; otherwise criterion
|
|
989
|
+
// 2 would pass a unit-level tracker test while the projected frame draws the wrong sub-draws.
|
|
990
|
+
if (
|
|
991
|
+
state.blocked === undefined &&
|
|
992
|
+
(object as { isBatchedMesh?: boolean }).isBatchedMesh === true
|
|
993
|
+
) {
|
|
994
|
+
state.blocked = {
|
|
995
|
+
code: "unsupportedObject",
|
|
996
|
+
reason: "an authored BatchedMesh has private per-sub-draw state the mirror cannot reproduce",
|
|
997
|
+
};
|
|
998
|
+
}
|
|
999
|
+
if ((object as { isLOD?: boolean }).isLOD === true) {
|
|
1000
|
+
state.renderables += 1;
|
|
1001
|
+
workspace.seen.add(object);
|
|
1002
|
+
addExactEntry(workspace, object, "lod");
|
|
1003
|
+
return;
|
|
1004
|
+
}
|
|
1005
|
+
if (!isRenderable(object)) return;
|
|
1006
|
+
state.renderables += 1;
|
|
1007
|
+
workspace.seen.add(object);
|
|
1008
|
+
if ((object as SkinnedMesh).isSkinnedMesh === true) {
|
|
1009
|
+
const skinnedReason = skinnedLaneReason(object);
|
|
1010
|
+
if (skinnedReason === undefined) {
|
|
1011
|
+
workspace.skinned[workspace.skinnedCount] = object as SkinnedMesh;
|
|
1012
|
+
workspace.skinnedCount += 1;
|
|
1013
|
+
} else addExactEntry(workspace, object, skinnedReason);
|
|
1014
|
+
return;
|
|
1015
|
+
}
|
|
1016
|
+
const reason = walkLaneReason(object);
|
|
1017
|
+
if (reason === undefined && isMesh(object)) {
|
|
1018
|
+
workspace.eligible[workspace.eligibleCount] = object;
|
|
1019
|
+
workspace.eligibleCount += 1;
|
|
1020
|
+
} else addExactEntry(workspace, object, reason ?? "unsupportedGeometry");
|
|
1021
|
+
}
|
|
1022
|
+
|
|
1023
|
+
function walkProjection(source: Scene, workspace: IProjectionScanWorkspace): IProjectionWalkState {
|
|
1024
|
+
const state: IProjectionWalkState = { renderables: 0 };
|
|
1025
|
+
const roots = source.children;
|
|
1026
|
+
for (let index = roots.length - 1; index >= 0; index -= 1) {
|
|
1027
|
+
workspace.walkStack[workspace.walkStackCount] = roots[index] as Object3D;
|
|
1028
|
+
workspace.walkStackCount += 1;
|
|
1029
|
+
}
|
|
1030
|
+
while (workspace.walkStackCount > 0) {
|
|
1031
|
+
workspace.walkStackCount -= 1;
|
|
1032
|
+
const object = workspace.walkStack[workspace.walkStackCount] as Object3D;
|
|
1033
|
+
workspace.walkStack[workspace.walkStackCount] = undefined;
|
|
1034
|
+
visitProjectionObject(object, workspace, state);
|
|
1035
|
+
if (isLight(object) || (object as { isLOD?: boolean }).isLOD === true) continue;
|
|
1036
|
+
const children = object.children;
|
|
1037
|
+
for (let index = children.length - 1; index >= 0; index -= 1) {
|
|
1038
|
+
workspace.walkStack[workspace.walkStackCount] = children[index] as Object3D;
|
|
1039
|
+
workspace.walkStackCount += 1;
|
|
1040
|
+
}
|
|
1041
|
+
}
|
|
1042
|
+
return state;
|
|
1043
|
+
}
|
|
1044
|
+
|
|
1045
|
+
function groupEligibleMeshes(workspace: IProjectionScanWorkspace, scanNumber: number): void {
|
|
1046
|
+
for (let index = 0; index < workspace.eligibleCount; index += 1) {
|
|
1047
|
+
addToBatchGroup(workspace, workspace.eligible[index] as Mesh, scanNumber);
|
|
1048
|
+
}
|
|
1049
|
+
for (let index = 0; index < workspace.skinnedCount; index += 1) {
|
|
1050
|
+
addToSkinnedGroup(workspace, workspace.skinned[index] as SkinnedMesh, scanNumber);
|
|
1051
|
+
}
|
|
1052
|
+
// Meshes whose own (geometry, material, flags) group is too small to instance-batch are exactly
|
|
1053
|
+
// the population a material-keyed batch exists for — distinct geometries over a shared surface. A
|
|
1054
|
+
// mesh whose geometry group made the floor never reaches here; instancing stays its lane, and it
|
|
1055
|
+
// references its geometry live rather than through a packed copy.
|
|
1056
|
+
//
|
|
1057
|
+
// The uniform pass runs first, because it is the only one of the two that can collapse these
|
|
1058
|
+
// meshes into a *single* draw: a packed batch is still one sub-draw per member on WebGPU, while a
|
|
1059
|
+
// per-instance colour over one shared geometry is one draw however many members it holds. A mesh
|
|
1060
|
+
// whose uniform group made the floor is claimed by it and never filed here.
|
|
1061
|
+
for (let index = 0; index < workspace.activeGroupCount; index += 1) {
|
|
1062
|
+
const group = workspace.activeGroups[index] as IProjectionBatchGroup;
|
|
1063
|
+
if (group.memberCount >= MIN_BATCH_MEMBERS) continue;
|
|
1064
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
1065
|
+
addToUniformGroup(workspace, group.members[member] as Mesh, scanNumber);
|
|
1066
|
+
}
|
|
1067
|
+
}
|
|
1068
|
+
for (let index = 0; index < workspace.activeGroupCount; index += 1) {
|
|
1069
|
+
const group = workspace.activeGroups[index] as IProjectionBatchGroup;
|
|
1070
|
+
if (group.memberCount >= MIN_BATCH_MEMBERS) continue;
|
|
1071
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
1072
|
+
const mesh = group.members[member] as Mesh;
|
|
1073
|
+
if (uniformClaimed(workspace, mesh)) continue;
|
|
1074
|
+
addToMaterialGroup(workspace, mesh, scanNumber);
|
|
1075
|
+
}
|
|
1076
|
+
}
|
|
1077
|
+
watchMaterialGroupGeometries(workspace);
|
|
1078
|
+
}
|
|
1079
|
+
|
|
1080
|
+
/**
|
|
1081
|
+
* A skinned group is one draw per pass however many rigs it holds; below the floor each rig keeps
|
|
1082
|
+
* its own, exactly as it had. Groups that make the floor are claimed into the plan here.
|
|
1083
|
+
*/
|
|
1084
|
+
function predictSkinnedDraws(workspace: IProjectionScanWorkspace): number {
|
|
1085
|
+
let draws = 0;
|
|
1086
|
+
for (let index = 0; index < workspace.activeSkinnedGroupCount; index += 1) {
|
|
1087
|
+
const group = workspace.activeSkinnedGroups[index] as IProjectionBatchGroup;
|
|
1088
|
+
if (group.memberCount < MIN_BATCH_MEMBERS) {
|
|
1089
|
+
draws += group.memberCount;
|
|
1090
|
+
continue;
|
|
1091
|
+
}
|
|
1092
|
+
workspace.skinnedGroups[workspace.skinnedGroupCount] = group;
|
|
1093
|
+
workspace.skinnedGroupCount += 1;
|
|
1094
|
+
draws += 1;
|
|
1095
|
+
}
|
|
1096
|
+
return draws;
|
|
1097
|
+
}
|
|
1098
|
+
|
|
1099
|
+
function predictDraws(workspace: IProjectionScanWorkspace): number {
|
|
1100
|
+
let predictedDraws = workspace.exactLaneCount;
|
|
1101
|
+
// A uniform group is one instanced draw however many members it holds, which is the whole reason
|
|
1102
|
+
// it exists: unlike the packed lane below, its members do not become one sub-draw each. Claimed
|
|
1103
|
+
// here so the same source cannot be drawn twice — once as an instance and once on the exact lane.
|
|
1104
|
+
for (let index = 0; index < workspace.activeUniformGroupCount; index += 1) {
|
|
1105
|
+
const group = workspace.activeUniformGroups[index] as IProjectionUniformGroup;
|
|
1106
|
+
if (group.memberCount < MIN_BATCH_MEMBERS) continue;
|
|
1107
|
+
workspace.batchGroups[workspace.batchGroupCount] = group;
|
|
1108
|
+
workspace.batchGroupCount += 1;
|
|
1109
|
+
predictedDraws += 1;
|
|
1110
|
+
}
|
|
1111
|
+
// A BatchedMesh still executes one multidraw sub-draw per visible member on WebGPU, so charge
|
|
1112
|
+
// every material-group member rather than pretending the packed object is one draw. The group
|
|
1113
|
+
// still earns admission when the aggregate plan beats the authored candidate count: it removes
|
|
1114
|
+
// renderer objects and gives the backend per-member frustum culling. Claiming the members here
|
|
1115
|
+
// keeps them out of the below-floor exact lane, so the same source cannot be drawn twice.
|
|
1116
|
+
for (let index = 0; index < workspace.activeMaterialGroupCount; index += 1) {
|
|
1117
|
+
const group = workspace.activeMaterialGroups[index] as IProjectionMaterialGroup;
|
|
1118
|
+
if (group.memberCount < MIN_BATCH_MEMBERS) continue;
|
|
1119
|
+
workspace.materialGroups[workspace.materialGroupCount] = group;
|
|
1120
|
+
workspace.materialGroupCount += 1;
|
|
1121
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
1122
|
+
workspace.materialClaims.set(group.members[member] as Mesh, workspace.scanNumber);
|
|
1123
|
+
}
|
|
1124
|
+
predictedDraws += group.memberCount;
|
|
1125
|
+
}
|
|
1126
|
+
predictedDraws += predictSkinnedDraws(workspace);
|
|
1127
|
+
for (let index = 0; index < workspace.activeGroupCount; index += 1) {
|
|
1128
|
+
const group = workspace.activeGroups[index] as IProjectionBatchGroup;
|
|
1129
|
+
if (group.memberCount < MIN_BATCH_MEMBERS) {
|
|
1130
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
1131
|
+
const mesh = group.members[member] as Mesh;
|
|
1132
|
+
if (
|
|
1133
|
+
workspace.materialClaims.get(mesh) !== workspace.scanNumber &&
|
|
1134
|
+
!uniformClaimed(workspace, mesh)
|
|
1135
|
+
)
|
|
1136
|
+
predictedDraws += 1;
|
|
1137
|
+
}
|
|
1138
|
+
} else {
|
|
1139
|
+
workspace.batchGroups[workspace.batchGroupCount] = group;
|
|
1140
|
+
workspace.batchGroupCount += 1;
|
|
1141
|
+
predictedDraws += 1;
|
|
1142
|
+
}
|
|
1143
|
+
}
|
|
1144
|
+
return predictedDraws;
|
|
1145
|
+
}
|
|
1146
|
+
|
|
1147
|
+
function collectBelowFloor(workspace: IProjectionScanWorkspace): void {
|
|
1148
|
+
for (let index = 0; index < workspace.activeSkinnedGroupCount; index += 1) {
|
|
1149
|
+
const group = workspace.activeSkinnedGroups[index] as IProjectionBatchGroup;
|
|
1150
|
+
if (group.memberCount >= MIN_BATCH_MEMBERS) continue;
|
|
1151
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
1152
|
+
workspace.belowFloor[workspace.belowFloorCount] = group.members[member] as Mesh;
|
|
1153
|
+
workspace.belowFloorCount += 1;
|
|
1154
|
+
}
|
|
1155
|
+
}
|
|
1156
|
+
for (let index = 0; index < workspace.activeGroupCount; index += 1) {
|
|
1157
|
+
const group = workspace.activeGroups[index] as IProjectionBatchGroup;
|
|
1158
|
+
if (group.memberCount >= MIN_BATCH_MEMBERS) continue;
|
|
1159
|
+
for (let member = 0; member < group.memberCount; member += 1) {
|
|
1160
|
+
const mesh = group.members[member] as Mesh;
|
|
1161
|
+
// Claimed by a batched material or uniform group this scan: it is already an instance inside
|
|
1162
|
+
// a batch, not below the floor. Everything else here — including members evicted from a
|
|
1163
|
+
// material group by the stream watch, whose geometry groups are always below the floor — keeps
|
|
1164
|
+
// its own draw. A material group needs no sweep of its own: every one of its members came from
|
|
1165
|
+
// a below-floor geometry group, so this loop already reaches each of them exactly once.
|
|
1166
|
+
if (workspace.materialClaims.get(mesh) === workspace.scanNumber) continue;
|
|
1167
|
+
if (uniformClaimed(workspace, mesh)) continue;
|
|
1168
|
+
workspace.belowFloor[workspace.belowFloorCount] = mesh;
|
|
1169
|
+
workspace.belowFloorCount += 1;
|
|
1170
|
+
}
|
|
1171
|
+
}
|
|
1172
|
+
}
|
|
1173
|
+
|
|
1174
|
+
/**
|
|
1175
|
+
* Walks the authored scene once and decides what this frame's projection will do.
|
|
1176
|
+
*
|
|
1177
|
+
* One traversal does all of it: classification, dirty detection and removal. Walking it twice
|
|
1178
|
+
* would double the only cost that scales with the scene. An explicit walk rather than
|
|
1179
|
+
* `Object3D.traverse`, because some subtrees must be mirrored whole and not descended into — an
|
|
1180
|
+
* `LOD` chooses one level per frame on itself, so its levels belong to its stand-in.
|
|
1181
|
+
*/
|
|
1182
|
+
export function scanProjection(
|
|
1183
|
+
source: Scene,
|
|
1184
|
+
minMeshes: number,
|
|
1185
|
+
workspace: IProjectionScanWorkspace,
|
|
1186
|
+
): IProjectionScanResult {
|
|
1187
|
+
releaseProjectionScanWorkspace(workspace);
|
|
1188
|
+
workspace.seen.begin();
|
|
1189
|
+
workspace.scanNumber += 1;
|
|
1190
|
+
const state = walkProjection(source, workspace);
|
|
1191
|
+
|
|
1192
|
+
if (state.blocked !== undefined) {
|
|
1193
|
+
return {
|
|
1194
|
+
exactLane: workspace.exactLane,
|
|
1195
|
+
exactLaneCount: workspace.exactLaneCount,
|
|
1196
|
+
plan: {
|
|
1197
|
+
action: "decline",
|
|
1198
|
+
reasonCode: state.blocked.code,
|
|
1199
|
+
reason: state.blocked.reason,
|
|
1200
|
+
},
|
|
1201
|
+
renderables: state.renderables,
|
|
1202
|
+
seen: workspace.seen,
|
|
1203
|
+
};
|
|
1204
|
+
}
|
|
1205
|
+
if (workspace.eligibleCount + workspace.skinnedCount * SKINNED_FLOOR_WEIGHT < minMeshes) {
|
|
1206
|
+
return {
|
|
1207
|
+
exactLane: workspace.exactLane,
|
|
1208
|
+
exactLaneCount: workspace.exactLaneCount,
|
|
1209
|
+
plan: {
|
|
1210
|
+
action: "decline",
|
|
1211
|
+
reasonCode: "belowMeshFloor",
|
|
1212
|
+
reason: `fewer than ${minMeshes} batchable meshes; the mirror would cost more than it saves`,
|
|
1213
|
+
},
|
|
1214
|
+
renderables: state.renderables,
|
|
1215
|
+
seen: workspace.seen,
|
|
1216
|
+
};
|
|
1217
|
+
}
|
|
1218
|
+
|
|
1219
|
+
groupEligibleMeshes(workspace, workspace.scanNumber);
|
|
1220
|
+
const predictedDraws = predictDraws(workspace);
|
|
1221
|
+
if (predictedDraws > state.renderables * WORTHWHILE_DRAW_RATIO) {
|
|
1222
|
+
return {
|
|
1223
|
+
exactLane: workspace.exactLane,
|
|
1224
|
+
exactLaneCount: workspace.exactLaneCount,
|
|
1225
|
+
plan: {
|
|
1226
|
+
action: "decline",
|
|
1227
|
+
reasonCode: "notWorthwhile",
|
|
1228
|
+
reason: `projecting would draw ${predictedDraws} of ${state.renderables} candidates, which is not worth its own cost`,
|
|
1229
|
+
},
|
|
1230
|
+
renderables: state.renderables,
|
|
1231
|
+
seen: workspace.seen,
|
|
1232
|
+
};
|
|
1233
|
+
}
|
|
1234
|
+
|
|
1235
|
+
collectBelowFloor(workspace);
|
|
1236
|
+
return {
|
|
1237
|
+
exactLane: workspace.exactLane,
|
|
1238
|
+
exactLaneCount: workspace.exactLaneCount,
|
|
1239
|
+
plan: {
|
|
1240
|
+
action: "project",
|
|
1241
|
+
batchGroups: workspace.batchGroups,
|
|
1242
|
+
batchGroupCount: workspace.batchGroupCount,
|
|
1243
|
+
materialGroups: workspace.materialGroups,
|
|
1244
|
+
materialGroupCount: workspace.materialGroupCount,
|
|
1245
|
+
skinnedGroups: workspace.skinnedGroups,
|
|
1246
|
+
skinnedGroupCount: workspace.skinnedGroupCount,
|
|
1247
|
+
belowFloor: workspace.belowFloor,
|
|
1248
|
+
belowFloorCount: workspace.belowFloorCount,
|
|
1249
|
+
exactLane: workspace.exactLane,
|
|
1250
|
+
exactLaneCount: workspace.exactLaneCount,
|
|
1251
|
+
lights: workspace.lights,
|
|
1252
|
+
lightCount: workspace.lightCount,
|
|
1253
|
+
seen: workspace.seen,
|
|
1254
|
+
},
|
|
1255
|
+
renderables: state.renderables,
|
|
1256
|
+
seen: workspace.seen,
|
|
1257
|
+
};
|
|
1258
|
+
}
|