@threenative/core 0.3.4 → 0.3.5

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.
Files changed (176) hide show
  1. package/capabilities.json +1505 -79
  2. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  3. package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  4. package/dist/{game-CljaDv4D.d.ts → game-Bj8G1wmD.d.ts} +102 -11
  5. package/dist/hot.d.ts +4 -4
  6. package/dist/index.d.ts +712 -118
  7. package/dist/index.js +12423 -4955
  8. package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
  9. package/dist/playtest.d.ts +6 -10
  10. package/dist/playtest.js +47 -24
  11. package/dist/react-css.d.ts +62 -0
  12. package/dist/react-css.js +591 -0
  13. package/dist/react.d.ts +2 -2
  14. package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
  15. package/dist/terrain-jobs-worker.d.ts +2 -0
  16. package/dist/terrain-jobs-worker.js +130 -0
  17. package/dist/ui-layer.js +59 -8
  18. package/dist/world.d.ts +766 -73
  19. package/dist/world.js +9307 -3543
  20. package/gpl/recipes/export_world.py +18 -1
  21. package/mcp/blender-server.mjs +7 -4
  22. package/mcp/blender.mjs +3 -4
  23. package/mcp/engine-server.mjs +2 -2
  24. package/mcp/servers.mjs +4 -4
  25. package/package.json +15 -9
  26. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  27. package/patches/three@0.185.1.patch +6594 -700
  28. package/scripts/apply-three-patch.mjs +62 -4
  29. package/src/animation-blend.ts +264 -0
  30. package/src/animation-composition.ts +362 -0
  31. package/src/animation-layers.ts +260 -0
  32. package/src/animation-root-motion.ts +283 -0
  33. package/src/animation.ts +896 -0
  34. package/src/assets.ts +1303 -0
  35. package/src/atmosphere/index.ts +335 -0
  36. package/src/atmosphere/luts.ts +298 -0
  37. package/src/atmosphere/params.ts +323 -0
  38. package/src/audio.ts +912 -0
  39. package/src/billboard.ts +124 -0
  40. package/src/bone-lengths.ts +157 -0
  41. package/src/camera-shake.ts +116 -0
  42. package/src/canvas-layer.ts +47 -0
  43. package/src/clip-audit.ts +401 -0
  44. package/src/clustered-batch.ts +492 -0
  45. package/src/clustered-mesh.ts +638 -0
  46. package/src/compute-driven.ts +176 -0
  47. package/src/compute-timing.ts +318 -0
  48. package/src/config.ts +593 -0
  49. package/src/debug.ts +82 -0
  50. package/src/engine-render-hook.ts +25 -0
  51. package/src/entities.ts +79 -0
  52. package/src/entity-snapshot.ts +53 -0
  53. package/src/flight.ts +683 -0
  54. package/src/fluid-field.ts +748 -0
  55. package/src/fluid-particles.ts +1253 -0
  56. package/src/frame-budget.ts +1368 -0
  57. package/src/game.ts +2390 -0
  58. package/src/geometry-capture.ts +1098 -0
  59. package/src/gpu-class.ts +160 -0
  60. package/src/gpu-frame-observation.ts +424 -0
  61. package/src/gpu-readback.ts +143 -0
  62. package/src/gpu-scene-bvh.ts +464 -0
  63. package/src/grounding.ts +100 -0
  64. package/src/hot.ts +161 -0
  65. package/src/import-meta.d.ts +13 -0
  66. package/src/index.ts +1536 -0
  67. package/src/input.ts +690 -0
  68. package/src/instanced-batch-lod.ts +283 -0
  69. package/src/instanced-batch.ts +274 -0
  70. package/src/interpolation.ts +129 -0
  71. package/src/launch-diagnostics.ts +161 -0
  72. package/src/loop.ts +564 -0
  73. package/src/matrix-world.ts +245 -0
  74. package/src/merge-parts.ts +812 -0
  75. package/src/model-lod.ts +1315 -0
  76. package/src/net-protocol.ts +333 -0
  77. package/src/net-session.ts +477 -0
  78. package/src/net.ts +80 -0
  79. package/src/ocean/fft.ts +72 -0
  80. package/src/ocean/spectral.ts +728 -0
  81. package/src/particle-significance.ts +102 -0
  82. package/src/particles.ts +648 -0
  83. package/src/path-follow.ts +175 -0
  84. package/src/picking.ts +250 -0
  85. package/src/pipeline-census.ts +1566 -0
  86. package/src/platform.ts +210 -0
  87. package/src/playtest.ts +839 -0
  88. package/src/pointer-events.ts +411 -0
  89. package/src/pose-measure.ts +435 -0
  90. package/src/profiling/FrameCounters.ts +231 -0
  91. package/src/profiling/Spans.ts +548 -0
  92. package/src/profiling/opacity-convention.ts +21 -0
  93. package/src/profiling/render-list-validate.ts +175 -0
  94. package/src/profiling/render-trap-audit.ts +84 -0
  95. package/src/profiling/scene-warning.ts +190 -0
  96. package/src/profiling/span-probes.ts +191 -0
  97. package/src/profiling/unlit-foliage-warning.ts +149 -0
  98. package/src/projection-apply.ts +1529 -0
  99. package/src/projection-marker.ts +142 -0
  100. package/src/projection-plan.ts +1258 -0
  101. package/src/projection-skinned.ts +419 -0
  102. package/src/projection-stability.ts +409 -0
  103. package/src/projection-uniform.ts +328 -0
  104. package/src/random.ts +41 -0
  105. package/src/react-css.ts +604 -0
  106. package/src/react-glyphs.ts +114 -0
  107. package/src/react-host.ts +576 -0
  108. package/src/react-layout.ts +265 -0
  109. package/src/react.ts +60 -0
  110. package/src/render/alpha-antialiasing.ts +159 -0
  111. package/src/render/batched-velocity.ts +126 -0
  112. package/src/render/chain.ts +1021 -0
  113. package/src/render/daylight.ts +189 -0
  114. package/src/render/depth-pyramid.ts +596 -0
  115. package/src/render/foliage-alpha.ts +166 -0
  116. package/src/render/material-key.ts +60 -0
  117. package/src/render/mesh-pool.ts +144 -0
  118. package/src/render/probe-volume.ts +1668 -0
  119. package/src/render/resolution-subrect.ts +253 -0
  120. package/src/render/velocity.ts +442 -0
  121. package/src/render/virtual-shadow-pages.ts +827 -0
  122. package/src/render/virtual-shadow-partial.ts +174 -0
  123. package/src/render/virtual-shadow.ts +3330 -0
  124. package/src/render/world-impostor-surface.ts +722 -0
  125. package/src/render/world-impostor.ts +558 -0
  126. package/src/render-camera-cull.ts +441 -0
  127. package/src/render-pass-budget.ts +501 -0
  128. package/src/renderProjection.ts +758 -0
  129. package/src/renderer-config.ts +127 -0
  130. package/src/renderer.ts +1847 -0
  131. package/src/replay-protocol.ts +85 -0
  132. package/src/replay.ts +205 -0
  133. package/src/resolution-scaler.ts +819 -0
  134. package/src/rig-preparation.ts +271 -0
  135. package/src/ripple-field.ts +432 -0
  136. package/src/scale.ts +109 -0
  137. package/src/scene.ts +239 -0
  138. package/src/schedule.ts +155 -0
  139. package/src/skeletal-mesh.ts +61 -0
  140. package/src/skeleton.ts +100 -0
  141. package/src/snow-field.ts +744 -0
  142. package/src/softbody-topology.ts +269 -0
  143. package/src/softbody.ts +516 -0
  144. package/src/sprite-animator.ts +222 -0
  145. package/src/startup-readiness.ts +386 -0
  146. package/src/state.ts +66 -0
  147. package/src/static-transform.ts +274 -0
  148. package/src/storage-buffer.ts +253 -0
  149. package/src/streaming.ts +308 -0
  150. package/src/target-fps.ts +92 -0
  151. package/src/terrain-jobs-worker.ts +17 -0
  152. package/src/terrain-jobs.ts +353 -0
  153. package/src/textures.ts +39 -0
  154. package/src/tracers.ts +237 -0
  155. package/src/ui-bridge.ts +368 -0
  156. package/src/ui-hit-regions.ts +380 -0
  157. package/src/ui-layer.ts +83 -0
  158. package/src/ui-state.ts +220 -0
  159. package/src/version.ts +2 -0
  160. package/src/viewport.ts +253 -0
  161. package/src/warmup.ts +1357 -0
  162. package/src/water-surface.ts +384 -0
  163. package/src/wave-field.ts +524 -0
  164. package/src/world-capabilities.ts +131 -0
  165. package/src/world-cell-proxy.ts +392 -0
  166. package/src/world-cells.ts +10564 -0
  167. package/src/world-gpu-scene.ts +3354 -0
  168. package/src/world-heightmap.ts +82 -0
  169. package/src/world-package.ts +469 -0
  170. package/src/world-passes.ts +582 -0
  171. package/src/world-region.ts +17 -0
  172. package/src/world-terrain-splat.ts +564 -0
  173. package/src/world-tiles.ts +3826 -0
  174. package/src/world-topology.ts +370 -0
  175. package/src/world-validate.ts +48 -0
  176. package/src/world.ts +805 -0
@@ -0,0 +1,3354 @@
1
+ import {
2
+ type BufferAttribute,
3
+ type Camera,
4
+ type DepthTexture,
5
+ Frustum,
6
+ Matrix4,
7
+ PerspectiveCamera,
8
+ Vector3,
9
+ Vector4,
10
+ } from "three";
11
+ import {
12
+ Fn,
13
+ If,
14
+ Loop,
15
+ Return,
16
+ abs,
17
+ atomicAdd,
18
+ float,
19
+ instanceIndex,
20
+ int,
21
+ length,
22
+ max,
23
+ min,
24
+ storage,
25
+ struct,
26
+ uniform,
27
+ vec3,
28
+ } from "three/tsl";
29
+ import {
30
+ IndirectStorageBufferAttribute,
31
+ ReadbackBuffer,
32
+ StorageBufferAttribute,
33
+ StorageInstancedBufferAttribute,
34
+ } from "three/webgpu";
35
+ import { biasedLodDistance } from "./model-lod.js";
36
+ import {
37
+ DepthPyramid,
38
+ type IKernelOcclusion,
39
+ type OcclusionMode,
40
+ occludedBy,
41
+ } from "./render/depth-pyramid.js";
42
+ import type { IRendererLike } from "./renderer.js";
43
+
44
+ /**
45
+ * The GPU-driven main pass of a streamed world: one compute dispatch culls and LOD-selects every
46
+ * resident placement, appends the survivors into a shared compacted matrix buffer, and each main
47
+ * batch draws its own region of that buffer with the instance count living in a GPU-side
48
+ * `DrawIndexedIndirect` record. The CPU keeps only the coarse per-key visibility.
49
+ *
50
+ * Everything the kernel needs is GPU data. The CPU writes the placement buffer when residency
51
+ * changes and the indirect records when a key is minted, retired or regrown — a structural event —
52
+ * and nothing at all per instance per frame.
53
+ *
54
+ * The per-instance logic exists twice on purpose: {@link cullAndSelect} is the reference, in plain
55
+ * TypeScript, and the TSL kernel below mirrors it line for line. The tests run in node with no GPU,
56
+ * so the reference is what is proved against the CPU path; the kernel is compiled in the browser.
57
+ */
58
+
59
+ /** Words one placement record holds: `mat4` + `centre` (xyz, radius) + `info` (asset slot, …; not `meta`, a reserved WGSL keyword). */
60
+ const PLACEMENT_WORDS = 24;
61
+ /** `DrawIndexedIndirect`: indexCount, instanceCount, firstIndex, baseVertex, firstInstance. */
62
+ const DRAW_ARGS_WORDS = 5;
63
+ /** The same record in bytes, which is the unit `BufferGeometry.setIndirect` takes its offset in. */
64
+ export const DRAW_ARGS_BYTES = DRAW_ARGS_WORDS * 4;
65
+
66
+ /**
67
+ * How many words the args buffer holds for `keys` keys: one indirect record each, plus one word
68
+ * each of measured-occlusion tally past the last record.
69
+ *
70
+ * The tally rides this buffer rather than a buffer of its own so a measured run reads the two out
71
+ * of the one readback the GPU-selected tally already issues on its own clock — a second readback on
72
+ * a second buffer is a second queue submission per window for eight bytes.
73
+ */
74
+ function argsWords(keys: number): number {
75
+ return keys * DRAW_ARGS_WORDS + keys;
76
+ }
77
+ /** One `vec4` per key, per asset slot and per level gate. */
78
+ const VEC4_WORDS = 4;
79
+ /** `mat4` per key: the part's own offset inside the model, the same matrix the CPU composes. */
80
+ const LOCAL_WORDS = 16;
81
+ /** Slots a placement may name before the kernel is refused rather than read out of bounds. */
82
+ const SLOT_NONE = -1;
83
+
84
+ /**
85
+ * One element of every WGSL type this module declares a storage buffer as, in array words.
86
+ *
87
+ * A storage binding's minimum size is one element of its declared type: a `mat4` buffer is 64 bytes
88
+ * whether it holds one matrix or a thousand, and a bound buffer under that is not a wrong picture but
89
+ * a refused pipeline — every dispatch on it is invalid, silently, and only the device complains. So
90
+ * the element count and the element size are not two independent numbers here: they are written down
91
+ * together, once, and every buffer is allocated from this table and nowhere else.
92
+ */
93
+ const STORAGE_WORDS = {
94
+ /** `mat4` + `centre` (vec4) + `info` (vec4), so one placement is 96 bytes and one stride. */
95
+ // quality-allow: the object key is the WGSL type name the kernel reads, so it keeps that spelling.
96
+ // biome-ignore lint/style/useNamingConvention: the key is the WGSL type, spelled as the kernel declares it.
97
+ GpuPlacement: PLACEMENT_WORDS,
98
+ /** `mat4`, one per key: the part's own offset inside the model, the same one the CPU composes. */
99
+ mat4: LOCAL_WORDS,
100
+ /** `DrawIndexedIndirect`'s five words; `uint` is one word, so the element count is the word count. */
101
+ uint: 1,
102
+ /** One `vec4` per key, per asset slot and per level gate. */
103
+ vec4: VEC4_WORDS,
104
+ } as const;
105
+
106
+ /** A WGSL type the cull kernel declares a storage buffer as, and {@link STORAGE_WORDS}'s key. */
107
+ export type StorageType = keyof typeof STORAGE_WORDS;
108
+
109
+ /** Bytes one element of `type` occupies, which is what a storage binding of it must be at least. */
110
+ export function storageElementBytes(type: StorageType): number {
111
+ return STORAGE_WORDS[type] * 4;
112
+ }
113
+
114
+ /**
115
+ * One storage attribute holding `count` elements — at least one, because a zero-element binding is
116
+ * a zero-byte buffer and zero bytes is under every declared type — of the WGSL `type` the kernel
117
+ * binds it as.
118
+ *
119
+ * The class and the array class are parameters because three's three storage attributes differ only
120
+ * in what the renderer does with them, and this module needs all three: a plain one, the instanced
121
+ * buffer a dressed batch's `instanceMatrix` is, and the indirect records `BufferGeometry.setIndirect`
122
+ * reads. Handing the item size in by hand is how `drawn` was allocated four words wide and bound as
123
+ * a `mat4`: a one-element, 16-byte buffer against a 64-byte requirement, so the cull kernel never
124
+ * ran on a real GPU at all. The size is not a free choice here, so it is not written at a call site.
125
+ */
126
+ function storageAttribute<A extends BufferAttribute>(
127
+ ctor: new (count: Float32Array | Uint32Array, itemSize: number) => A,
128
+ type: StorageType,
129
+ count: number,
130
+ array: Float32ArrayConstructor | Uint32ArrayConstructor = Float32Array,
131
+ ): A {
132
+ const words = STORAGE_WORDS[type];
133
+ return new ctor(new array(Math.max(1, count) * words), words);
134
+ }
135
+ /** Dispatches between readbacks: a mapped buffer is a queue submission, so not every frame. */
136
+ const VALIDATE_EVERY = 30;
137
+ /**
138
+ * Dispatches between the tally's own readbacks, on the same budget as a validation.
139
+ *
140
+ * The tally reads the same indirect args buffer a validation reads, so it reuses that readback path
141
+ * and the renderer's one staging buffer rather than adding a second copy: when validation is on its
142
+ * landed bytes feed the tally, and when it is off this is the interval alone.
143
+ */
144
+ const TALLY_EVERY = 30;
145
+ /** Keys a mismatch line names before the rest are counted and not printed. */
146
+ const VALIDATE_REPORTED_KEYS = 10;
147
+ /** Keys a matrix or indirect-record line names, which carry more numbers than a count line does. */
148
+ const MATRIX_REPORTED_KEYS = 5;
149
+ /** Meshes a `mesh=` line names, on the same budget as the record lines above. */
150
+ const MESH_REPORTED_MESHES = 5;
151
+ /** Two matrices within this of each other are the same one written through a `mat4` product. */
152
+ const MATRIX_TOLERANCE = 1e-3;
153
+ /** Characters of a cause a `cause=` line carries, so one message cannot own the report. */
154
+ const CAUSE_CHARS = 160;
155
+
156
+ /**
157
+ * A `mat4` world matrix, the placement's bounding-sphere centre and radius, and the asset slot whose
158
+ * gates pick its level. One stride, so the CPU's `Float32Array` is the GPU's storage buffer with no
159
+ * repacking and no type punning: the radius and the slot are small and exactly representable.
160
+ */
161
+ const PlacementStruct = struct({ matrix: "mat4", centre: "vec4", info: "vec4" }, "GpuPlacement");
162
+
163
+ /** One resident placement as the source buffer holds it. */
164
+ export interface IGpuPlacement {
165
+ readonly matrix: Float32Array;
166
+ /** X, Y, Z and the bounding-sphere radius; the frustum test reads the first three. */
167
+ readonly centre: Float32Array;
168
+ /** The asset slot in `0`; `SLOT_NONE` for a record whose cell has left the ring. */
169
+ slot: number;
170
+ /**
171
+ * The placement's uniform scale, in `info.y`: the whole-asset impostor's terminal gate is the
172
+ * base-sphere projected distance scaled by this, so a placement scaled ten times does not switch
173
+ * to the atlas until it is ten times as far. `1` when a caller does not carry one.
174
+ */
175
+ scale?: number;
176
+ }
177
+
178
+ /** One asset's slots: its level gates and the keys each level's parts draw into. */
179
+ export interface IAssetSlot {
180
+ /** Level switch distances, ascending, `0` first; the same numbers the CPU path crosses at. */
181
+ readonly distances: readonly number[];
182
+ /** `maxDistance` less its eighth, or `undefined` for an asset with no cull distance. */
183
+ readonly cull: number | undefined;
184
+ /** Per level: the first key its parts draw into and how many parts it has. */
185
+ readonly levels: readonly { readonly firstKey: number; readonly parts: number }[];
186
+ /**
187
+ * Whether the last level is a whole-asset impostor: its gate is the base-sphere projected
188
+ * distance, and the placement's own scale is applied to it at selection. The reference and the
189
+ * kernel both read it, so an impostor terminal and an authored one cannot be crossed differently.
190
+ */
191
+ readonly impostor?: boolean;
192
+ /** Derived LODs keep the last casting shape; authored LODs may opt out. Defaults to true. */
193
+ readonly shadowFallback?: boolean;
194
+ }
195
+
196
+ /** One key's region of the shared drawn buffer, and the args record that counts it. */
197
+ export interface IRegion {
198
+ /** Where this key's survivors are written. Moves only in a re-layout, which rewrites every record. */
199
+ start: number;
200
+ /** Instances this region holds. Grows only in a re-layout, which resizes the whole level. */
201
+ capacity: number;
202
+ readonly argsIndex: number;
203
+ /** The part's own offset inside the model; drawn as `placement * local`, as the CPU does. */
204
+ readonly local: Float32Array;
205
+ /** The main key this region is, which is what the validation marker names a mismatch by. */
206
+ readonly name?: string;
207
+ /**
208
+ * The dressed geometry's own index count, which the record's `indexCount` has to say for the draw
209
+ * to name a triangle at all. The owner records it when it dresses the mesh — the scene does not
210
+ * know what shape a key draws — and the validation holds the record against it.
211
+ */
212
+ indexCount: number;
213
+ /**
214
+ * This key has no shadow twin (its level is past the world's `castLevels`), so a shadow map drops
215
+ * a placement the main pass draws here. The GPU twin reads the same fact as `keys.w`, which only a
216
+ * minted twin sets.
217
+ */
218
+ readonly uncast?: boolean;
219
+ }
220
+
221
+ /**
222
+ * One storage attribute widened by doubling until it holds `needed`, or itself when it already does.
223
+ * The contents are carried over and marked as one upload range, which is what makes a regrow a copy
224
+ * rather than a fresh zeroed buffer.
225
+ */
226
+ function growBuffer<A extends BufferAttribute>(
227
+ current: A,
228
+ needed: number,
229
+ make: (count: number) => A,
230
+ ): A {
231
+ if (current.count >= needed) return current;
232
+ let capacity = Math.max(1, current.count);
233
+ while (capacity < needed) capacity *= 2;
234
+ const grown = make(capacity);
235
+ grown.array.set(current.array as Uint32Array);
236
+ grown.addUpdateRange(0, current.array.length);
237
+ return grown;
238
+ }
239
+
240
+ /** Adds an update range, extending the last one when the new range touches or overlaps it. */
241
+ export function addRange(
242
+ attribute: {
243
+ updateRanges: { start: number; count: number }[];
244
+ addUpdateRange(start: number, count: number): void;
245
+ },
246
+ start: number,
247
+ count: number,
248
+ ): void {
249
+ const last = attribute.updateRanges[attribute.updateRanges.length - 1];
250
+ if (last === undefined || start > last.start + last.count || start + count < last.start) {
251
+ attribute.addUpdateRange(start, count);
252
+ return;
253
+ }
254
+ const newStart = Math.min(last.start, start);
255
+ // Set the count first. It is measured from the old start.
256
+ last.count = Math.max(last.start + last.count, start + count) - newStart;
257
+ last.start = newStart;
258
+ }
259
+
260
+ /** One level's parts and the single capacity all of them are sized from. */
261
+ interface ILevelGroup {
262
+ capacity: number;
263
+ /**
264
+ * The key index the level's run starts at, claimed whole at its first key and never moved, so
265
+ * `firstKey + part` names that part's own key however the parts were minted. The run is claimed
266
+ * rather than appended to because keys are not minted in level order: a prewarm mints every level
267
+ * and part of one asset before the next, a walk that arrives mid-prewarm mints whatever its cell
268
+ * needs, and the keys minted in between are not this level's. A run built by appending is a run
269
+ * with another asset's keys inside it, and a gate table that names it draws that asset's placements
270
+ * through this level's parts and this level's placements through the other's — which is a forest
271
+ * drawn with another tree's geometry, and a check that reproduces the same addressing reads it as
272
+ * agreement.
273
+ */
274
+ firstKey: number;
275
+ /** How many parts the level has, which is the width of the run the gate table names. */
276
+ parts: number;
277
+ /** Part index to the region that part draws into; laid out in this order. */
278
+ readonly minted: Map<number, number>;
279
+ }
280
+
281
+ /**
282
+ * Which of a level's parts a key is, so the parts of one level stay the contiguous run the kernel
283
+ * and the gate table both address as `firstKey + part`. `undefined` mints a key of its own, which
284
+ * is every key a caller that has no level to be a part of wants.
285
+ */
286
+ export interface ILevelKey {
287
+ /** The level this part belongs to — one group, however many parts it has. */
288
+ readonly group: string;
289
+ /** The part's own index in that level, which is the order the group is laid out in. */
290
+ readonly part: number;
291
+ /**
292
+ * How many parts the level has altogether, so the run is claimed once and in full. The caller knows
293
+ * it: the level is an array of parts, and every part of it will be asked for. A part outside the
294
+ * run the level declared is refused rather than laid over another level's key.
295
+ */
296
+ readonly parts: number;
297
+ }
298
+
299
+ /** The offset a part that has not been minted yet draws with: none at all, and nowhere to draw. */
300
+ const NO_LOCAL = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
301
+
302
+ /** What the kernel reads, and the whole of what a dispatch touches. */
303
+ export interface IKernelInput {
304
+ readonly placements: readonly IGpuPlacement[];
305
+ readonly count: number;
306
+ readonly camera: {
307
+ readonly planes: Float32Array;
308
+ readonly x: number;
309
+ readonly y: number;
310
+ readonly z: number;
311
+ };
312
+ readonly slots: readonly IAssetSlot[];
313
+ readonly regions: readonly IRegion[];
314
+ readonly regionCount: number;
315
+ /**
316
+ * The hierarchical-depth occlusion test, when a launch asked for one. Absent, the frustum is the
317
+ * whole visibility rule; present, every placement the frustum kept is reprojected into the
318
+ * pyramid's own frame and tested. See {@link IKernelOcclusion}.
319
+ */
320
+ readonly occlusion?: IKernelOcclusion;
321
+ }
322
+
323
+ /** What one dispatch produced: the compacted survivors and the per-key instance counts. */
324
+ export interface IKernelResult {
325
+ /** `DRAW_ARGS_WORDS` per region, `1` the instance count; everything else is the CPU's. */
326
+ readonly args: Uint32Array;
327
+ readonly drawn: Float32Array;
328
+ /** Instances drawn per region, which is what the args record's count must say. */
329
+ readonly counts: Uint32Array;
330
+ /**
331
+ * What the pyramid test hid, and only when one ran: the instances and the triangles of every
332
+ * placement it would have dropped. Absent is "no test ran", never "the test hid nothing" — a
333
+ * measured run reads these while drawing every one of them.
334
+ */
335
+ readonly occluded?: { readonly instances: number; readonly triangles: number };
336
+ }
337
+
338
+ /**
339
+ * One dispatch's own copy of everything its kernel read, taken while that dispatch runs, plus the
340
+ * attribute the readback has to name.
341
+ *
342
+ * A streamed world changes its placement set, its gate table and its region layout between one frame
343
+ * and the next, so a reference computed when a readback lands describes the frames that followed the
344
+ * dispatch that produced the bytes — which is how a check that compared nothing came to report
345
+ * `compared=0` over 21,147 resident placements. Copied at dispatch time, the reference is a pure
346
+ * function of the snapshot and nothing that happens afterwards can change it.
347
+ */
348
+ interface IValidationSnapshot extends IKernelInput {
349
+ /** The indirect records this dispatch wrote, which is what its readback must name. */
350
+ readonly args: unknown;
351
+ /** The shared matrix buffer this dispatch compacted into, which its other readback must name. */
352
+ readonly drawn: unknown;
353
+ /** Resident placements the scene held when this dispatch ran. */
354
+ readonly placed: number;
355
+ }
356
+
357
+ interface IValidationReadbacks {
358
+ readonly args: ReadbackBuffer;
359
+ readonly drawn: ReadbackBuffer;
360
+ }
361
+
362
+ /**
363
+ * The level one placement draws with, from an asset's gate table and the placement's own scale.
364
+ *
365
+ * Every gate but a whole-asset impostor's terminal is an authored world-metre distance, compared
366
+ * directly. The impostor's terminal gate is the base-sphere *projected* distance: the atlas is
367
+ * built for the asset's own LOD0 size, so a placement scaled ten times reaches the atlas ten times
368
+ * as far — its threshold is `base * |scale|`, floored by the last source gate it must stay strictly
369
+ * beyond. The floor is nudged one representable step past that gate: sharing the gate's own switch
370
+ * distance would let the terminal overwrite the last source level at every distance past it, so the
371
+ * source level would never draw. Read by {@link cullAndSelect} and mirrored by the kernel and the
372
+ * CPU path, so all three cross the same switch.
373
+ */
374
+ export function levelAtGates(
375
+ slot: Pick<IAssetSlot, "distances" | "impostor">,
376
+ distance: number,
377
+ scale: number,
378
+ ): number {
379
+ const last = slot.distances.length - 1;
380
+ const magnitude = Number.isFinite(scale) ? Math.abs(scale) : 1;
381
+ let level = 0;
382
+ for (let index = 1; index < slot.distances.length; index += 1) {
383
+ const gate = slot.distances[index] as number;
384
+ const threshold =
385
+ slot.impostor === true && index === last && last >= 1
386
+ ? Math.max(strictlyAfterGate(slot.distances[last - 1] as number), gate * magnitude)
387
+ : gate;
388
+ if (distance > threshold) level = index;
389
+ }
390
+ return level;
391
+ }
392
+
393
+ /**
394
+ * The last level at or below `level` that the scene can actually draw, which is where a placement
395
+ * goes when the gates name one the prewarm has not minted keys for.
396
+ *
397
+ * `WorldCells#gatesOf` names every level of an asset from the moment it is adopted and fills in the
398
+ * keys minted so far, so a chain that has widened holds `parts: 2,0,0,0` while the loading screen is
399
+ * up. The CPU path draws `asset.levels[level]` whatever the gates name and always has a shape there;
400
+ * a dispatch that took the named level would loop its zero keys and draw the placement nowhere, and
401
+ * with the bias raised the placements past the last source gate are exactly the far ones — a forest
402
+ * 80-300 m out standing in its own shadows, while the shadow halves, which take no bias and key
403
+ * themselves, still draw. One level down is the finest shape the scene holds, which is the level the
404
+ * prewarm is one frame from minting.
405
+ */
406
+ function drawableLevel(slot: Pick<IAssetSlot, "levels">, level: number): number {
407
+ for (let at = level; at > 0; at -= 1) if ((slot.levels[at]?.parts ?? 0) > 0) return at;
408
+ return 0;
409
+ }
410
+
411
+ /**
412
+ * The level a shadow map draws a placement at, or -1 when no level of its asset casts. A placement
413
+ * whose main level casts nothing falls back only when its asset permits it: derived chains past
414
+ * `castLevels` keep their shadow, drawn in the last shape that has a twin, rather than
415
+ * leaving a hole in the map (PRD-541). The level is then floored at the map's base and clamped to
416
+ * the last level that casts, so a coarse map draws the coarsest shape that has a twin. `base` past
417
+ * the chain is clamped by the chain length first.
418
+ */
419
+ function shadowLevel(
420
+ slot: Pick<IAssetSlot, "levels" | "shadowFallback">,
421
+ regions: readonly IRegion[],
422
+ drawn: number,
423
+ base: number,
424
+ ): number {
425
+ const casts = (at: number): boolean => {
426
+ const gate = slot.levels[at];
427
+ return gate !== undefined && gate.parts > 0 && regions[gate.firstKey]?.uncast !== true;
428
+ };
429
+ if (slot.shadowFallback === false && casts(drawn) === false) return -1;
430
+ // At or below `drawn` any casting level qualifies, above it only up to the map's base, so the
431
+ // last casting level in `[0, max(drawn, base)]` is both rules at once.
432
+ const last = Math.max(drawn, Math.min(base, slot.levels.length - 1));
433
+ let level = -1;
434
+ for (let at = 0; at <= last; at += 1) if (casts(at)) level = at;
435
+ return level;
436
+ }
437
+
438
+ /**
439
+ * One representable Float32 step past a gate: `g * (1 + 2^-22)`, two f32 ULPs at `g`'s exponent.
440
+ *
441
+ * A floored terminal gate must start strictly after the source gate it is floored by and must stay
442
+ * so once the threshold is stored and compared in f32, which a bare `g` does not: the terminal
443
+ * shares `g`'s switch distance and the later gate wins every comparison, starving the source level.
444
+ * A relative step, not a fixed metre margin, so the ordering holds at every authored scale.
445
+ */
446
+ const GATE_STEP = 2 ** -22;
447
+
448
+ function strictlyAfterGate(gate: number): number {
449
+ return gate + Math.abs(gate) * GATE_STEP;
450
+ }
451
+
452
+ /**
453
+ * One shadow map's own three numbers, which is the whole of what a level render knows that the main
454
+ * camera does not.
455
+ *
456
+ * They are the level's, never the camera's: a map's frustum is the light's window, its gate is the
457
+ * texel size it can resolve, and its base is the chain level the cluster path hands it — `#probe`
458
+ * swaps a coarse level's geometry for the coarsest shape, so a coarse map draws that shape whatever a
459
+ * placement's own distance would have selected. The distance itself is the main pass's, from the
460
+ * eye: a placement's shape and its cast come from the key the main pass draws it in.
461
+ */
462
+ export interface IShadowLevel {
463
+ /** The six frustum planes of this map's own shadow camera. */
464
+ readonly planes: Float32Array;
465
+ /** This map's texel gate in world metres: a placement narrower than it casts nothing here. */
466
+ readonly gate: number;
467
+ /**
468
+ * The chain level this map draws at, floored over the placement's own. 0 is the placement's own
469
+ * LOD by distance — what the finest map draws — and the coarsest index is what every level past
470
+ * the first draws. A base whose keys are not minted draws nothing, which is why a caller settling
471
+ * the prewarm first is the contract rather than a fallback.
472
+ *
473
+ * {@link COARSEST_SHADOW_LEVEL} is past every chain, and means the coarsest shape an asset has: a
474
+ * map that coarsens its casters does not know how long each asset's chain is, and the floor is
475
+ * clamped per asset, so one number asks every chain for its own coarsest level.
476
+ */
477
+ readonly base: number;
478
+ }
479
+
480
+ /**
481
+ * A {@link IShadowLevel.base} past every chain: the map draws every asset's coarsest shape, whatever
482
+ * distance selected it. Clamped to each asset's own last level, so an owner with no level count to
483
+ * hand — `VirtualShadowNode`, which coarsens a coarse level's casters without knowing an asset —
484
+ * can still ask.
485
+ */
486
+ export const COARSEST_SHADOW_LEVEL = 1 << 20;
487
+
488
+ /**
489
+ * The per-instance kernel, in plain TypeScript. The TSL kernel in {@link WorldGpuScene} is this
490
+ * loop with the same branches, and the test proves this one against the CPU path.
491
+ *
492
+ * One placement, in the order the source buffer holds them: a released record and a record whose
493
+ * asset is unknown are skipped, the bounding sphere is tested against the camera's six planes, the
494
+ * XZ distance picks the level through the asset's own gates and culls a record beyond its cull
495
+ * distance, and each part of that level takes the next free slot in its key's region and writes
496
+ * `placement * part offset` there. A region that is full is a dropped instance, never a write past
497
+ * the end of the buffer.
498
+ */
499
+ export function cullAndSelect(input: IKernelInput): IKernelResult {
500
+ return select(input, undefined);
501
+ }
502
+
503
+ /**
504
+ * The same kernel with a shadow map's own four numbers in place of the camera's, and nothing else
505
+ * changed: same regions, same keys, same `placement * part offset`, same capacity guard.
506
+ *
507
+ * The gate is applied to the placement's own diameter, where the cluster path applies it to the
508
+ * whole mesh and drops the square with it — so on a uniform-size fixture the two sets are the same
509
+ * set, and where a square mixes sizes this one is the finer of the two.
510
+ */
511
+ export function cullAndSelectShadow(input: IKernelInput, level: IShadowLevel): IKernelResult {
512
+ return select(input, level);
513
+ }
514
+
515
+ /**
516
+ * The one loop both references share. `shadow` is what makes the second one a variant rather than a
517
+ * fork: the main camera's planes, eye, no gate and no base are the degenerate case, so the two can
518
+ * never disagree by having been edited apart.
519
+ */
520
+ function select(input: IKernelInput, shadow: IShadowLevel | undefined): IKernelResult {
521
+ const { placements, camera, regions, slots } = input;
522
+ // A shadow map has no main camera to reproject into, so the test is the main pass's alone — a
523
+ // caster the eye cannot see still casts.
524
+ const occlusion = shadow === undefined ? input.occlusion : undefined;
525
+ const planes = shadow?.planes ?? camera.planes;
526
+ const metres = shadow?.gate ?? 0;
527
+ const base = shadow?.base ?? 0;
528
+ const counts = new Uint32Array(input.regionCount);
529
+ const args = new Uint32Array(input.regionCount * DRAW_ARGS_WORDS);
530
+ // The drawn buffer is the regions' own, so the reference allocates exactly what the GPU holds.
531
+ const capacity = regions.reduce(
532
+ (sum, region) => Math.max(sum, region.start + region.capacity),
533
+ 0,
534
+ );
535
+ const matrix = new Float32Array(capacity * LOCAL_WORDS);
536
+ for (const region of regions) {
537
+ args[region.argsIndex * DRAW_ARGS_WORDS + 4] = region.start;
538
+ }
539
+ let occludedInstances = 0;
540
+ let occludedTriangles = 0;
541
+ for (let index = 0; index < input.count; index += 1) {
542
+ const placement = placements[index];
543
+ if (placement === undefined || placement.slot < 0) continue;
544
+ const slot = slots[placement.slot];
545
+ if (slot === undefined) continue;
546
+ const at = placement.centre;
547
+ const radius = at[3] as number;
548
+ let visible = true;
549
+ for (let plane = 0; plane < 6; plane += 1) {
550
+ const offset = plane * 4;
551
+ const signed =
552
+ (planes[offset] as number) * (at[0] as number) +
553
+ (planes[offset + 1] as number) * (at[1] as number) +
554
+ (planes[offset + 2] as number) * (at[2] as number) +
555
+ (planes[offset + 3] as number);
556
+ if (signed < -radius) {
557
+ visible = false;
558
+ break;
559
+ }
560
+ }
561
+ if (visible === false) continue;
562
+ // Sub-texel, exactly as `#probe` decides it for a mesh: a caster this map cannot resolve casts
563
+ // no shadow a fragment could tell from ground cover.
564
+ if (radius * 2 < metres) continue;
565
+ const distance = Math.hypot((at[0] as number) - camera.x, (at[2] as number) - camera.z);
566
+ if (slot.cull !== undefined && distance > slot.cull) continue;
567
+ // Cull above is the authored distance; the level below is the biased one for the main pass — the
568
+ // same multiplier the kernel's uniform carries, so the reference and the dispatch cross a switch
569
+ // together. A shadow map takes the main pass's own level, from the eye: that is the key a
570
+ // placement is drawn in, and the cluster path casts each key's placements from that key's mesh.
571
+ const drawn = drawableLevel(
572
+ slot,
573
+ levelAtGates(slot, biasedLodDistance(distance), placement.scale ?? 1),
574
+ );
575
+ const level = shadow === undefined ? drawn : shadowLevel(slot, regions, drawn, base);
576
+ if (level < 0) continue;
577
+ const gate = slot.levels[level];
578
+ if (gate === undefined) continue;
579
+ const hidden =
580
+ occlusion !== undefined && occludedBy(occlusion, at, radius) ? occlusion : undefined;
581
+ for (let part = 0; part < gate.parts; part += 1) {
582
+ const region = regions[gate.firstKey + part];
583
+ if (region === undefined) continue;
584
+ // Counted either way: a measured run draws what it hides, so the count is the only place the
585
+ // answer can live.
586
+ if (hidden !== undefined) {
587
+ occludedInstances += 1;
588
+ occludedTriangles += region.indexCount / 3;
589
+ if (hidden.cull) continue;
590
+ }
591
+ const taken = counts[gate.firstKey + part] as number;
592
+ if (taken >= region.capacity) continue;
593
+ counts[gate.firstKey + part] = taken + 1;
594
+ args[region.argsIndex * DRAW_ARGS_WORDS + 1] = taken + 1;
595
+ compose(placement.matrix, region.local, matrix, (region.start + taken) * LOCAL_WORDS);
596
+ }
597
+ }
598
+ return {
599
+ args,
600
+ counts,
601
+ drawn: matrix,
602
+ ...(occlusion === undefined
603
+ ? {}
604
+ : { occluded: { instances: occludedInstances, triangles: occludedTriangles } }),
605
+ };
606
+ }
607
+
608
+ /**
609
+ * One asset's gates as its owner last published them: the source representation and its
610
+ * `asset.distances`/`cullDistance(definition.maxDistance)` snapshot at the completed swap boundary.
611
+ *
612
+ * Deliberately not an {@link IAssetSlot}. A slot is what this class wrote into its own table, and a
613
+ * table written before the owner's model widened its chain is the exact thing the check exists to
614
+ * catch — feeding it back in as the reference is the check agreeing with itself.
615
+ */
616
+ export interface ILiveAsset {
617
+ /** The asset id a main key is named `asset:level:part` with, which is the owner's own convention. */
618
+ readonly id: string;
619
+ /** Level switch distances, ascending, `0` first — the CPU publication snapshot. */
620
+ readonly distances: readonly number[];
621
+ /** `maxDistance` less its eighth, or `undefined`. */
622
+ readonly cull: number | undefined;
623
+ /** Index-aligned with `distances`; each level's parts, each part's own offset inside the model. */
624
+ readonly locals: readonly (readonly Float32Array[])[];
625
+ /** Whether the last level is a whole-asset impostor whose gate the placement's scale scales. */
626
+ readonly impostor?: boolean;
627
+ }
628
+
629
+ /**
630
+ * Every placement's own answer, from the owner's live gates, as the instances each main key must be
631
+ * holding: the same six-plane sphere test, the same `cull`, the same ascending `distance > gate`
632
+ * level test and the same `placement * part offset` composition {@link cullAndSelect} runs — over
633
+ * gates this file did not write.
634
+ *
635
+ * This is the one reference in the module that is not a mirror of the kernel's inputs. `cullAndSelect`
636
+ * reads the gate table out of the same class the kernel's buffer is written from, so a table holding
637
+ * the wrong distances makes both agree; here the caller passes the owner's own `distances`, so a
638
+ * table that was written before the chain widened, or before the last `maxDistance`, answers
639
+ * differently from the picture the CPU path draws.
640
+ */
641
+ export function liveKeyInstances(
642
+ placements: readonly IGpuPlacement[],
643
+ asset: (slot: number) => ILiveAsset | undefined,
644
+ camera: {
645
+ readonly planes: Float32Array;
646
+ readonly x: number;
647
+ readonly y: number;
648
+ readonly z: number;
649
+ },
650
+ ): Map<string, Float32Array> {
651
+ const words = new Map<string, number[]>();
652
+ for (const placement of placements) {
653
+ if (placement.slot < 0) continue;
654
+ const held = asset(placement.slot);
655
+ if (held === undefined) continue;
656
+ const at = placement.centre;
657
+ const radius = at[3] as number;
658
+ let visible = true;
659
+ for (let plane = 0; plane < 6; plane += 1) {
660
+ const offset = plane * 4;
661
+ const signed =
662
+ (camera.planes[offset] as number) * (at[0] as number) +
663
+ (camera.planes[offset + 1] as number) * (at[1] as number) +
664
+ (camera.planes[offset + 2] as number) * (at[2] as number) +
665
+ (camera.planes[offset + 3] as number);
666
+ if (signed < -radius) {
667
+ visible = false;
668
+ break;
669
+ }
670
+ }
671
+ if (visible === false) continue;
672
+ const distance = Math.hypot((at[0] as number) - camera.x, (at[2] as number) - camera.z);
673
+ if (held.cull !== undefined && distance > held.cull) continue;
674
+ // The dispatch's own bias and the same gate rule: this reference is what the dressed mesh's
675
+ // instances are checked against, so it must cross the impostor switch exactly as the kernel does.
676
+ const level = levelAtGates(held, biasedLodDistance(distance), placement.scale ?? 1);
677
+ const locals = held.locals[level];
678
+ if (locals === undefined) continue;
679
+ for (const [part, local] of locals.entries()) {
680
+ const key = `${held.id}:${String(level)}:${String(part)}`;
681
+ let run = words.get(key);
682
+ if (run === undefined) {
683
+ run = [];
684
+ words.set(key, run);
685
+ }
686
+ compose(placement.matrix, local, LIVE_MATRIX, 0);
687
+ for (const word of LIVE_MATRIX) run.push(word);
688
+ }
689
+ }
690
+ return new Map([...words].map(([key, run]) => [key, Float32Array.from(run)]));
691
+ }
692
+
693
+ /** The one matrix `liveKeyInstances` composes into, reused per placement as the kernel's own is. */
694
+ const LIVE_MATRIX = new Float32Array(LOCAL_WORDS);
695
+
696
+ /**
697
+ * Whether two gate tables are the same one, so a level key minted after the table was written
698
+ * rewrites it and a swap that arrives with nothing new does not. A level the world has not minted a
699
+ * key for carries `parts: 0`, which is what the kernel's own loop then draws for it: nothing.
700
+ */
701
+ function sameGates(one: IAssetSlot, other: IAssetSlot): boolean {
702
+ if (one.cull !== other.cull) return false;
703
+ if ((one.shadowFallback === false) !== (other.shadowFallback === false)) return false;
704
+ if ((one.impostor === true) !== (other.impostor === true)) return false;
705
+ if (one.distances.length !== other.distances.length) return false;
706
+ for (const [index, distance] of one.distances.entries())
707
+ if (distance !== other.distances[index]) return false;
708
+ if (one.levels.length !== other.levels.length) return false;
709
+ for (const [index, level] of one.levels.entries()) {
710
+ const gate = other.levels[index];
711
+ if (gate === undefined || gate.firstKey !== level.firstKey || gate.parts !== level.parts)
712
+ return false;
713
+ }
714
+ return true;
715
+ }
716
+
717
+ /** One word of an indirect readback, out of range being the zero a record that was never written holds. */
718
+ function word(readback: Uint32Array, at: number): number {
719
+ return (readback[at] ?? 0) as number;
720
+ }
721
+
722
+ /** The translation of the `mat4` at slot `at`, which is what a draw places and a line can name. */
723
+ function xyz(matrices: Float32Array, at: number): string {
724
+ const matrix = at * LOCAL_WORDS;
725
+ if (matrix + LOCAL_WORDS > matrices.length) return "[]";
726
+ return (
727
+ `[${(matrices[matrix + 12] as number).toFixed(3)},` +
728
+ `${(matrices[matrix + 13] as number).toFixed(3)},` +
729
+ `${(matrices[matrix + 14] as number).toFixed(3)}]`
730
+ );
731
+ }
732
+
733
+ /**
734
+ * Whether two runs of `mat4` hold the same matrices, as a set and not as a sequence.
735
+ *
736
+ * The kernel appends through an atomic, so the order two dispatches fill a region's run in is the
737
+ * order the device scheduled them in and is not the order the reference walked the placements. The
738
+ * counts agree over a set that agrees; a set that does not is a run one slot out, a matrix that was
739
+ * never written, or a `firstInstance` the draw reads from a different place — none of which a count
740
+ * can see. Sorted by translation, because that is what orders a placement, and compared with a
741
+ * tolerance, because a matrix written through a product of two floats is not bit-equal to either.
742
+ */
743
+ function sameMatrices(
744
+ gpu: Float32Array,
745
+ gpuStart: number,
746
+ gpuCount: number,
747
+ cpu: Float32Array,
748
+ cpuStart: number,
749
+ cpuCount: number,
750
+ tolerance: number,
751
+ ): boolean {
752
+ const one = sorted(gpu, gpuStart, gpuCount);
753
+ const other = sorted(cpu, cpuStart, cpuCount);
754
+ if (one.length !== other.length) return false;
755
+ for (const [index, matrix] of one.entries()) {
756
+ const against = other[index] as Float32Array;
757
+ for (let word = 0; word < LOCAL_WORDS; word += 1)
758
+ if (Math.abs((matrix[word] as number) - (against[word] as number)) > tolerance) return false;
759
+ }
760
+ return true;
761
+ }
762
+
763
+ /**
764
+ * Whether two part offsets are the same matrix word for word. A re-dress copies the part's `Matrix4`
765
+ * into a fresh array, so a re-registration of the same key is the same `local` by value and not by
766
+ * reference; comparing the bytes is what makes it a no-op.
767
+ */
768
+ function sameLocal(one: Float32Array, other: Float32Array): boolean {
769
+ if (one.length !== other.length) return false;
770
+ for (let word = 0; word < one.length; word += 1)
771
+ if ((one[word] as number) !== (other[word] as number)) return false;
772
+ return true;
773
+ }
774
+
775
+ /** One run of `mat4` as views, ordered by translation, and short reads truncated rather than read past. */
776
+ function sorted(matrices: Float32Array, start: number, count: number): Float32Array[] {
777
+ const out: Float32Array[] = [];
778
+ for (let taken = 0; taken < count; taken += 1) {
779
+ const at = (start + taken) * LOCAL_WORDS;
780
+ if (at < 0 || at + LOCAL_WORDS > matrices.length) break;
781
+ out.push(matrices.subarray(at, at + LOCAL_WORDS));
782
+ }
783
+ out.sort(
784
+ (one, other) =>
785
+ (one[12] as number) - (other[12] as number) || (one[14] as number) - (other[14] as number),
786
+ );
787
+ return out;
788
+ }
789
+
790
+ /** `out * into` at `at`, column-major, which is the element order both matrices are written in. */ function compose(
791
+ out: Float32Array,
792
+ into: Float32Array,
793
+ target: Float32Array,
794
+ at: number,
795
+ ): void {
796
+ for (let column = 0; column < 4; column += 1)
797
+ for (let row = 0; row < 4; row += 1) {
798
+ let sum = 0;
799
+ for (let k = 0; k < 4; k += 1)
800
+ sum += (out[k * 4 + row] as number) * (into[column * 4 + k] as number);
801
+ target[at + column * 4 + row] = sum;
802
+ }
803
+ }
804
+
805
+ /**
806
+ * One dressed main mesh's draw, as the owner's own live state says it, and nothing from this file's
807
+ * tables.
808
+ *
809
+ * This is the check that cannot be wrong in the same way the kernel is. {@link cullAndSelect}
810
+ * addresses a level's parts as `levels[gate.x + level].y + part`, and the gate table holds the
811
+ * `firstKey` the source owner registered for that level, so a key/record/mesh mapping that is
812
+ * wrong is reproduced on both sides of the comparison and reads as agreement: a real WebGPU walk
813
+ * printed `ok` over a forest it was drawing with another tree's geometry. The three numbers here
814
+ * come from the other side of the seam — the mesh's own `geometry.indirect` record, the mesh's own
815
+ * name, and the instances the owner's own gates and the camera's own planes select for that name —
816
+ * so the one question they can answer is the one that matters: does the record this mesh draws from
817
+ * hold exactly the instances that mesh's key is owed.
818
+ */
819
+ export interface IMeshDraw {
820
+ /** The dressed mesh's own name, which is the main key: `asset:level:part`. */
821
+ readonly name: string;
822
+ /** `geometry.indirectOffset / DRAW_ARGS_BYTES` — the record the draw reads, not one the tables name. */
823
+ readonly record: number;
824
+ /**
825
+ * Every instance the owner's live gates and the camera's planes select for this key, `mat4` after
826
+ * `mat4`: the whole answer, and never the per-cell records this path's own refilter left behind.
827
+ */
828
+ readonly instances: Float32Array;
829
+ /**
830
+ * Whether the mesh's own geometry reads the args buffer the readback came from, at the record above:
831
+ * `geometry.indirect === scene.args` and `geometry.indirectOffset === region.argsIndex *
832
+ * DRAW_ARGS_BYTES`, answered by the owner from the actual mesh. A record offset can agree with the
833
+ * live buffer while the mesh still points at an older buffer with the same numeric offset — the
834
+ * args buffer is allocated independently of `drawn`, and a mint can replace it under a dressed mesh
835
+ * — so an offset check alone reads `ok` over a mesh drawing a buffer nothing writes. A missing value
836
+ * is not a pass: only `true` is bound.
837
+ */
838
+ readonly bound?: boolean;
839
+ }
840
+
841
+ /** What the independent per-mesh check found, in the shape the report folds in. */
842
+ export interface IMeshDrawComparison {
843
+ /** Meshes whose own record was read back and held against the live-state instances. */
844
+ readonly compared: number;
845
+ readonly mismatched: number;
846
+ readonly mismatches: readonly string[];
847
+ }
848
+
849
+ /**
850
+ * Every dressed main mesh's own record, against the instances its own key is owed, as a set rather
851
+ * than a sequence — the kernel appends through an atomic, so a device's order is not the CPU's.
852
+ *
853
+ * Equality, and not containment, because the reference is now the whole answer: the owner's gates
854
+ * and the camera's planes over the scene's own placements, which is everything the dispatch reads.
855
+ * Containment was the right relation when the other side was the CPU path's per-cell records, which
856
+ * are the records a refilter left and go stale the moment the GPU scene bypasses it — a reference
857
+ * that can be a superset cannot name a level selected at the wrong distance, and a far tree drawn
858
+ * at its near level is what that looks like in the picture.
859
+ */
860
+ export function compareMeshDraws(
861
+ gpu: Uint32Array,
862
+ drawn: Float32Array,
863
+ draws: readonly IMeshDraw[],
864
+ regions: readonly IRegion[],
865
+ ): IMeshDrawComparison {
866
+ const mismatches: string[] = [];
867
+ let mismatched = 0;
868
+ for (const draw of draws) {
869
+ const record = draw.record * DRAW_ARGS_WORDS;
870
+ const landed = word(gpu, record + 1);
871
+ const first = word(gpu, record + 4);
872
+ // A stale binding is a mismatch the counts and matrices cannot see: the mesh's own geometry
873
+ // points at an args buffer the readback did not come from, so whatever this record holds is not
874
+ // what that mesh draws. Only an explicit `true` is bound, so a caller that forgets the field
875
+ // fails closed rather than reading as agreement.
876
+ if (draw.bound !== true) {
877
+ mismatched += 1;
878
+ if (mismatches.length >= MESH_REPORTED_MESHES) continue;
879
+ const owner = regions.find((region) => region.argsIndex === draw.record);
880
+ mismatches.push(
881
+ `mesh=${draw.name} record=${String(draw.record)} ` +
882
+ `region=${owner?.name ?? "none"} indirect=stale count gpu=${String(landed)} ` +
883
+ `live=${String(draw.instances.length / LOCAL_WORDS)}`,
884
+ );
885
+ continue;
886
+ }
887
+ if (
888
+ sameMatrices(
889
+ drawn,
890
+ first,
891
+ landed,
892
+ draw.instances,
893
+ 0,
894
+ draw.instances.length / LOCAL_WORDS,
895
+ MATRIX_TOLERANCE,
896
+ )
897
+ )
898
+ continue;
899
+ mismatched += 1;
900
+ if (mismatches.length >= MESH_REPORTED_MESHES) continue;
901
+ // The region that owns the record the mesh read, which is the name that says whether the mesh
902
+ // and the scene ever agreed on which record this key is.
903
+ const owner = regions.find((region) => region.argsIndex === draw.record);
904
+ mismatches.push(
905
+ `mesh=${draw.name} record=${String(draw.record)} ` +
906
+ `region=${owner?.name ?? "none"} count gpu=${String(landed)} ` +
907
+ `live=${String(draw.instances.length / LOCAL_WORDS)} ` +
908
+ `firstMatrix gpu=${xyz(drawn, first)} live=${xyz(draw.instances, 0)}`,
909
+ );
910
+ }
911
+ return { compared: draws.length, mismatched, mismatches };
912
+ }
913
+
914
+ /** What one landed readback concluded, in the three words a log line can carry. */
915
+ export type GpuSceneVerdict = "ok" | "mismatch" | "error";
916
+
917
+ /** One landed readback's verdict, its one line, and the detail lines under it. */
918
+ export interface IGpuSceneValidation {
919
+ readonly verdict: GpuSceneVerdict;
920
+ readonly line: string;
921
+ readonly lines: readonly string[];
922
+ }
923
+
924
+ /**
925
+ * The memory numbers a validation line can carry, all of them optional.
926
+ *
927
+ * The first seven are three's `info.memory` fields (`WebGPURenderer`, 0.185); a backend that tracks
928
+ * none of them reports none, which is why every field is optional and only finite numbers are
929
+ * printed — an absent reading is not a zero. `footprintBytes` is the sum of this scene's own storage
930
+ * buffer `footprint()` bytes, the one number here Three did not write.
931
+ */
932
+ export type GpuSceneMemoryField =
933
+ | "storageAttributes"
934
+ | "storageAttributesSize"
935
+ | "indirectStorageAttributes"
936
+ | "indirectStorageAttributesSize"
937
+ | "readbackBuffers"
938
+ | "readbackBuffersSize"
939
+ | "total"
940
+ | "footprintBytes";
941
+
942
+ /** One validation's memory reading; a field is absent when the backend did not offer a finite one. */
943
+ export type GpuSceneMemory = Partial<Record<GpuSceneMemoryField, number>>;
944
+
945
+ const MEMORY_FIELDS = [
946
+ "storageAttributes",
947
+ "storageAttributesSize",
948
+ "indirectStorageAttributes",
949
+ "indirectStorageAttributesSize",
950
+ "readbackBuffers",
951
+ "readbackBuffersSize",
952
+ "total",
953
+ "footprintBytes",
954
+ ] as const satisfies readonly GpuSceneMemoryField[];
955
+
956
+ /**
957
+ * The one placement nearest the camera (in XZ) a zero/zero comparison was handed, as the dispatch's
958
+ * own snapshot held it. Every number is the snapshot's, never the live scene's: the camera's eye and
959
+ * this placement's sphere, root translation, slot, slot cull, horizontal distance and the margin to
960
+ * the nearest of the six frustum planes are what say whether the snapshot held no live source or
961
+ * held one the camera, sphere, range or frustum rejected. A field is omitted, not printed as a fake
962
+ * zero, when the snapshot has no finite number for it.
963
+ */
964
+ export interface IValidationNearest {
965
+ /** The bounding sphere: X, Y, Z and the radius. */
966
+ readonly centre: readonly [number, number, number];
967
+ readonly radius: number;
968
+ /** The placement matrix's translation, which is what a draw places. */
969
+ readonly root: readonly [number, number, number];
970
+ /** The asset slot the placement names. */
971
+ readonly slot: number;
972
+ /** The slot's authored cull distance, or absent when it has none. */
973
+ readonly cull?: number;
974
+ /** `hypot(cx - eye.x, cz - eye.z)`, the distance the level and cull gates read. */
975
+ readonly distance: number;
976
+ /** The least `plane·centre + plane.constant + radius` over the six planes: negative is rejected. */
977
+ readonly margin: number;
978
+ }
979
+
980
+ /**
981
+ * Why a comparison that landed both counts at zero was handed nothing: the snapshot's own camera eye,
982
+ * how many placements it held and how many of them were live, and the one live placement nearest the
983
+ * camera in XZ. Taken from the snapshot, so nothing that streams while the bytes are in flight can
984
+ * rewrite the answer. Attached only when `instancesGpu` and `instancesCpu` are both zero.
985
+ */
986
+ export interface IValidationProbe {
987
+ readonly eye: readonly [number, number, number];
988
+ /** Placements the snapshot held, live and released. */
989
+ readonly snapshot: number;
990
+ /** Placements whose slot was not `SLOT_NONE`, the only ones the kernel considers. */
991
+ readonly live: number;
992
+ /** Absent when the snapshot held no live placement to name. */
993
+ readonly nearest?: IValidationNearest;
994
+ }
995
+
996
+ /** What a landed readback is judged on, gathered from the scene before it is formatted. */
997
+ export interface IGpuSceneComparison {
998
+ /** Keys whose GPU instance count was read back and held against the reference. */
999
+ readonly compared: number;
1000
+ readonly instancesGpu: number;
1001
+ readonly instancesCpu: number;
1002
+ /** Up to {@link VALIDATE_REPORTED_KEYS} `name gpu=… cpu=…` lines; the count is the whole total. */
1003
+ readonly mismatches: readonly string[];
1004
+ readonly mismatched: number;
1005
+ /**
1006
+ * Keys whose drawn matrices, `firstInstance` or `indexCount` disagreed, and up to
1007
+ * {@link MATRIX_REPORTED_KEYS} of them by name. The counts above are what the dispatch promised;
1008
+ * these are what the draw reads, which is a different question and the one the picture answers.
1009
+ */
1010
+ readonly matricesMismatched: number;
1011
+ readonly matrixMismatches: readonly string[];
1012
+ /**
1013
+ * Dressed main meshes whose own record was read back and held against the CPU path's own records
1014
+ * for that mesh's key, and up to {@link MESH_REPORTED_MESHES} of them by name. This is the check
1015
+ * the reference above cannot make: a key/record/mesh mapping that is wrong is one both sides
1016
+ * reproduce, and a mesh drawing another asset's placements out of its own record is the picture
1017
+ * that proves it.
1018
+ */
1019
+ readonly meshMismatched: number;
1020
+ readonly meshMismatches: readonly string[];
1021
+ /** Resident placements the scene held when the readback was issued. */
1022
+ readonly placed: number;
1023
+ /** The device's last uncaptured error, or `""` for none since the last check reported one. */
1024
+ readonly deviceError: string;
1025
+ /** What stopped the check — a rejected readback, say. Non-empty is an `error` on its own. */
1026
+ readonly cause?: string;
1027
+ /**
1028
+ * What the device and this scene held when the check reported. Absent when neither offered a
1029
+ * finite number, and a field is omitted rather than printed as zero when its backend has none.
1030
+ */
1031
+ readonly memory?: GpuSceneMemory;
1032
+ /** The snapshot's own camera and nearest live placement, when both instance totals landed zero. */
1033
+ readonly probe?: IValidationProbe;
1034
+ }
1035
+
1036
+ /** One completed manual frame check, identified by the caller's frame and this scene's dispatch. */
1037
+ export interface IWorldGpuFrameValidation extends IGpuSceneComparison {
1038
+ /** The caller's rendered-frame identity, never inferred from readback timing. */
1039
+ readonly frame: number;
1040
+ /** The dispatch whose buffers and snapshot this readback completed against. */
1041
+ readonly dispatch: number;
1042
+ readonly verdict: GpuSceneVerdict;
1043
+ }
1044
+
1045
+ /**
1046
+ * The verdict and the lines one landed readback reports, as `TN_WORLD_GPU_SCENE_VALIDATE`.
1047
+ *
1048
+ * `ok` is a claim that the GPU drew what the reference draws, so it takes three things: every key's
1049
+ * count landing equal, every key's record and matrices landing where the reference put them, and
1050
+ * something to land. A dispatch the device refused leaves the args buffer holding what the clear
1051
+ * pass wrote, which compares equal to a scene with nothing in it — a real WebGPU run printed
1052
+ * `ok keys=0` 956 times while the cull pipeline was being refused for a binding 48 bytes short, which
1053
+ * is a check that reports success precisely when the kernel does nothing. So comparing nothing while
1054
+ * placements exist is an `error`, and a device that raised anything uncaptured is an `error`
1055
+ * whatever the counts say, because every count in a buffer the device has already invalidated is not
1056
+ * evidence of anything.
1057
+ *
1058
+ * The three mismatch families are counted apart and all are a `mismatch`: a key that drew the right
1059
+ * number of instances at the wrong place or through a record naming no triangle is the failure a
1060
+ * count cannot see, and a walk that printed `mismatched=0` over a forest it never drew is what that
1061
+ * reads like. The third is the one the two above cannot find at all: every key the reference names
1062
+ * and every record it reads is named by this same file, so a key/record/mesh mapping that is wrong is
1063
+ * one they both reproduce, and the dressed mesh's own record, against the CPU path's own records,
1064
+ * is the only pair of numbers here that were not written by the same hand.
1065
+ *
1066
+ * An `error` always names its cause on one `cause=` line: the checks that fail here fail silently
1067
+ * otherwise, and a line reading `error` with nothing after it is the report that hid a refused
1068
+ * pipeline in the first place.
1069
+ */
1070
+ /** One `[x,y,z]` at three decimals, the precision `xyz` names a matrix translation with. */
1071
+ function triple(values: readonly [number, number, number]): string {
1072
+ return (
1073
+ `[${(values[0] as number).toFixed(3)},` +
1074
+ `${(values[1] as number).toFixed(3)},${(values[2] as number).toFixed(3)}]`
1075
+ );
1076
+ }
1077
+
1078
+ /** The `key=value` fields a zero/zero comparison's probe adds after the memory fields. */
1079
+ function probeFields(probe: IValidationProbe): string[] {
1080
+ const out = [
1081
+ `eye=${triple(probe.eye)}`,
1082
+ `snapshot=${String(probe.snapshot)}`,
1083
+ `live=${String(probe.live)}`,
1084
+ ];
1085
+ const near = probe.nearest;
1086
+ if (near === undefined) return out;
1087
+ out.push(
1088
+ `nearSphere=${triple(near.centre)}`,
1089
+ `nearRadius=${near.radius.toFixed(3)}`,
1090
+ `nearRoot=${triple(near.root)}`,
1091
+ `nearSlot=${String(near.slot)}`,
1092
+ );
1093
+ if (near.cull !== undefined) out.push(`nearCull=${near.cull.toFixed(3)}`);
1094
+ out.push(`nearXZ=${near.distance.toFixed(3)}`, `nearMargin=${near.margin.toFixed(3)}`);
1095
+ return out;
1096
+ }
1097
+
1098
+ /**
1099
+ * The snapshot's own camera and nearest live placement, for a comparison both of whose counts landed
1100
+ * zero. The scan only picks the nearest; the six-plane margin is computed for that one placement
1101
+ * alone, not for every placement the reference walked, and a field the snapshot has no finite number
1102
+ * for is omitted rather than printed as a fake zero.
1103
+ */
1104
+ function zeroComparisonProbe(snapshot: IValidationSnapshot): IValidationProbe {
1105
+ const eye: readonly [number, number, number] = [
1106
+ snapshot.camera.x,
1107
+ snapshot.camera.y,
1108
+ snapshot.camera.z,
1109
+ ];
1110
+ let live = 0;
1111
+ let nearest: IGpuPlacement | undefined;
1112
+ let nearestDistance = Number.POSITIVE_INFINITY;
1113
+ for (const placement of snapshot.placements) {
1114
+ if (placement.slot < 0) continue;
1115
+ live += 1;
1116
+ const at = placement.centre;
1117
+ const distance = Math.hypot(
1118
+ (at[0] as number) - snapshot.camera.x,
1119
+ (at[2] as number) - snapshot.camera.z,
1120
+ );
1121
+ if (Number.isFinite(distance) && distance < nearestDistance) {
1122
+ nearestDistance = distance;
1123
+ nearest = placement;
1124
+ }
1125
+ }
1126
+ const probe: IValidationProbe = { eye, live, snapshot: snapshot.count };
1127
+ if (nearest === undefined) return probe;
1128
+ const at = nearest.centre;
1129
+ const radius = at[3] as number;
1130
+ const centre: readonly [number, number, number] = [
1131
+ at[0] as number,
1132
+ at[1] as number,
1133
+ at[2] as number,
1134
+ ];
1135
+ const root: readonly [number, number, number] = [
1136
+ nearest.matrix[12] as number,
1137
+ nearest.matrix[13] as number,
1138
+ nearest.matrix[14] as number,
1139
+ ];
1140
+ let margin = Number.POSITIVE_INFINITY;
1141
+ for (let plane = 0; plane < 6; plane += 1) {
1142
+ const offset = plane * 4;
1143
+ const signed =
1144
+ (snapshot.camera.planes[offset] as number) * (at[0] as number) +
1145
+ (snapshot.camera.planes[offset + 1] as number) * (at[1] as number) +
1146
+ (snapshot.camera.planes[offset + 2] as number) * (at[2] as number) +
1147
+ (snapshot.camera.planes[offset + 3] as number);
1148
+ margin = Math.min(margin, signed + radius);
1149
+ }
1150
+ const numbers = [...centre, ...root, radius, nearestDistance, margin];
1151
+ if (numbers.some((value) => !Number.isFinite(value))) return probe;
1152
+ const cull = snapshot.slots[nearest.slot]?.cull;
1153
+ return {
1154
+ ...probe,
1155
+ nearest: {
1156
+ centre,
1157
+ distance: nearestDistance,
1158
+ margin,
1159
+ radius,
1160
+ root,
1161
+ slot: nearest.slot,
1162
+ ...(cull === undefined ? {} : { cull }),
1163
+ },
1164
+ };
1165
+ }
1166
+
1167
+ export function validationReport(input: IGpuSceneComparison): IGpuSceneValidation {
1168
+ const blind = input.compared === 0 && input.placed > 0;
1169
+ const cause =
1170
+ input.deviceError !== ""
1171
+ ? `device-error ${input.deviceError}`
1172
+ : (input.cause ?? (blind ? `compared-0-with-placed=${String(input.placed)}` : ""));
1173
+ const verdict: GpuSceneVerdict =
1174
+ cause !== ""
1175
+ ? "error"
1176
+ : input.mismatched > 0 || input.matricesMismatched > 0 || input.meshMismatched > 0
1177
+ ? "mismatch"
1178
+ : "ok";
1179
+ const memory: string[] = [];
1180
+ if (input.memory !== undefined)
1181
+ for (const name of MEMORY_FIELDS) {
1182
+ const value = input.memory[name];
1183
+ if (typeof value === "number" && Number.isFinite(value))
1184
+ memory.push(`${name}=${String(value)}`);
1185
+ }
1186
+ const details = [...memory, ...(input.probe === undefined ? [] : probeFields(input.probe))];
1187
+ const suffix = details.length === 0 ? "" : ` ${details.join(" ")}`;
1188
+ const line =
1189
+ `TN_WORLD_GPU_SCENE_VALIDATE ${verdict} compared=${String(input.compared)} ` +
1190
+ `instancesGpu=${String(input.instancesGpu)} instancesCpu=${String(input.instancesCpu)} ` +
1191
+ `mismatched=${String(input.mismatched)} matricesMismatched=${String(input.matricesMismatched)} ` +
1192
+ `meshMismatched=${String(input.meshMismatched)}${suffix}`;
1193
+ const lines: string[] = [...input.mismatches, ...input.matrixMismatches, ...input.meshMismatches];
1194
+ if (cause !== "") lines.push(`cause=${cause.slice(0, CAUSE_CHARS)}`);
1195
+ return { verdict, line, lines };
1196
+ }
1197
+
1198
+ /** The message an uncaptured WebGPU error event carries, flattened to one line. */
1199
+ function uncapturedMessage(event: unknown): string {
1200
+ const error = (event as { error?: { message?: string; constructor?: { name?: string } } }).error;
1201
+ const kind = error?.constructor?.name ?? "GPUError";
1202
+ return `${kind}: ${(error?.message ?? "no message").replace(/\s+/gu, " ").trim()}`;
1203
+ }
1204
+
1205
+ /**
1206
+ * What `TN_WORLD_GPU_SCENE` reports, and what `stats().gpuScene` carries.
1207
+ *
1208
+ * `dispatches`/`instances`/`keys` are the scene's own tables — the placements it holds and the keys
1209
+ * it is ready to draw. The optional `gpu*` trio is different in kind: it is a sample of what the GPU
1210
+ * actually selected in the **main** pass, read back from the same indirect args records the draw
1211
+ * uses (sum of `instanceCount`, and sum of `instanceCount x indexCount / 3`). Shadow passes are not
1212
+ * tallied, and a count three reports from `renderer.info.render.triangles` is an upper bound over a
1213
+ * mesh's CPU capacity, not a GPU-selected count — see {@link IFrameBudgetWindow.mainGpuTriangles}.
1214
+ */
1215
+ export interface IWorldGpuSceneReport {
1216
+ readonly dispatches: number;
1217
+ readonly instances: number;
1218
+ readonly keys: number;
1219
+ readonly on: boolean;
1220
+ readonly reason: string;
1221
+ /** Instances the GPU selected in the main pass, from the last landed tally. */
1222
+ readonly gpuInstances?: number;
1223
+ /** Triangles the GPU selected in the main pass (`instanceCount x indexCount / 3`), from the tally. */
1224
+ readonly gpuTriangles?: number;
1225
+ /** Dispatches between the tally's bytes being issued and now; grows until the first lands. */
1226
+ readonly gpuTallyAgeFrames?: number;
1227
+ /**
1228
+ * What the pyramid occlusion test would cull, when a launch asked it to measure. Absent unless
1229
+ * `?tnOcclusion=measure` asked, `reason` names why it measured nothing (`no scene depth`), and the
1230
+ * counts and `occlusion.gpuTriangles` come from one landed dispatch, even if a later tally
1231
+ * was skipped for occlusion.
1232
+ */
1233
+ readonly occlusion?: {
1234
+ readonly mode: OcclusionMode;
1235
+ readonly reason: string;
1236
+ /** Pyramid levels and the dispatches that rebuild them each frame. */
1237
+ readonly levels: number;
1238
+ readonly buildDispatches: number;
1239
+ /** The last landed sample, and the mean over every sample that landed. */
1240
+ readonly instances: number;
1241
+ readonly triangles: number;
1242
+ readonly meanInstances: number;
1243
+ readonly meanTriangles: number;
1244
+ readonly samples: number;
1245
+ /** `triangles / gpuTriangles` of the same sample, which is what the go/no-go multiplies. */
1246
+ readonly share: number;
1247
+ readonly gpuTriangles: number;
1248
+ readonly ageFrames: number;
1249
+ };
1250
+ }
1251
+
1252
+ /**
1253
+ * The shadow twins' two buffers: a record per key and a run per key, at the layout the main pass
1254
+ * already gave each key. Allocated only once a provider has registered — see
1255
+ * {@link WorldGpuScene.shadowKeysFrom}.
1256
+ */
1257
+ interface IShadowBuffers {
1258
+ readonly args: IndirectStorageBufferAttribute;
1259
+ readonly drawn: StorageInstancedBufferAttribute;
1260
+ /** Key name to the main key index it twins, so a missing twin is a missing draw, not a crash. */
1261
+ readonly keys: Map<string, number>;
1262
+ /** The same indices the other way, so a record write knows whether this key has a twin at all. */
1263
+ readonly held: Set<number>;
1264
+ }
1265
+
1266
+ interface IGpuSceneBuffers {
1267
+ readonly args: IndirectStorageBufferAttribute;
1268
+ readonly drawn: StorageInstancedBufferAttribute;
1269
+ readonly gates: StorageBufferAttribute;
1270
+ readonly keys: StorageBufferAttribute;
1271
+ readonly levels: StorageBufferAttribute;
1272
+ readonly locals: StorageBufferAttribute;
1273
+ readonly source: StorageBufferAttribute;
1274
+ }
1275
+
1276
+ /** One of the scene's own storage buffers, by the name it is allocated and grown under. */
1277
+ type BufferName = keyof IGpuSceneBuffers;
1278
+
1279
+ /**
1280
+ * The declared WGSL type of every buffer that is a plain `StorageBufferAttribute` in
1281
+ * {@link IGpuSceneBuffers}. `args` and `drawn` are absent because each needs a three class of its own,
1282
+ * so `#growOf` names those two literally; the other five share one.
1283
+ */
1284
+ const STORAGE_PLAIN: Record<Exclude<BufferName, "args" | "drawn">, StorageType> = {
1285
+ gates: "vec4",
1286
+ keys: "vec4",
1287
+ levels: "vec4",
1288
+ locals: "mat4",
1289
+ source: "GpuPlacement",
1290
+ };
1291
+
1292
+ /** Resident placements the source buffer is sized to hold before the first reallocation. */
1293
+ const SOURCE_FLOOR = 16;
1294
+
1295
+ /** One storage buffer as the check reads it: the type the kernel declares and what was allocated. */
1296
+ export interface IGpuSceneBufferFootprint {
1297
+ readonly type: StorageType;
1298
+ readonly count: number;
1299
+ /** `array.byteLength` — the size WebGPU compares against one element of `type`. */
1300
+ readonly bytes: number;
1301
+ }
1302
+
1303
+ /** The slice of a `GPUDevice` the validation seam reads, so a test can stand in a fake. */
1304
+ interface IDeviceLike {
1305
+ onuncapturederror?: ((event: unknown) => void) | null;
1306
+ }
1307
+
1308
+ /**
1309
+ * Why the GPU scene is not on, when it is not.
1310
+ *
1311
+ * Three of the three: compute, storage buffers and indirect draws. WebGL has none of them, and a
1312
+ * native backend without them falls back to exactly the CPU path PRD-458 left behind — which is a
1313
+ * lost saving, never a wrong picture. `gpuScene: false` is the same answer for a game debugging it.
1314
+ */
1315
+ export function gpuSceneUnsupported(renderer: IRendererLike): string {
1316
+ if (renderer.kind !== "webgpu") return `backend=${renderer.kind}`;
1317
+ const raw = renderer.raw as {
1318
+ backend?: { device?: IDeviceLike; hasFeature?: (name: string) => boolean };
1319
+ };
1320
+ const backend = raw?.backend;
1321
+ if (backend === undefined || typeof backend.hasFeature !== "function")
1322
+ return "backend=webgpu-without-hasFeature";
1323
+ if (backend.hasFeature("core-features-and-limits") !== true) return "feature=core";
1324
+ if (backend.hasFeature("indirect-first-instance") !== true)
1325
+ return "feature=indirect-first-instance";
1326
+ return "";
1327
+ }
1328
+
1329
+ /** The six planes of a camera's frustum, as the kernel reads them, into `out`. */
1330
+ function cameraPlanes(camera: Camera, out: Float32Array): void {
1331
+ _cullFrustum.setFromProjectionMatrix(
1332
+ _proj.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse),
1333
+ );
1334
+ for (const [index, plane] of _cullFrustum.planes.entries()) {
1335
+ const at = index * 4;
1336
+ out[at] = plane.normal.x;
1337
+ out[at + 1] = plane.normal.y;
1338
+ out[at + 2] = plane.normal.z;
1339
+ out[at + 3] = plane.constant;
1340
+ }
1341
+ }
1342
+
1343
+ const _proj = new Matrix4();
1344
+ const _cullFrustum = new Frustum();
1345
+ const _eye = new Vector3();
1346
+ const _view = new Matrix4();
1347
+
1348
+ /** Camera travel in one dispatch that the occlusion test reads as a cut rather than a turn. */
1349
+ const OCCLUSION_CUT_METRES = 2;
1350
+
1351
+ /** Two projection matrices are unchanged when every element is within this. */
1352
+ const VIEW_EPSILON = 1e-6;
1353
+
1354
+ /** Whether the projection changed; ordinary camera travel and turns are not cuts. */
1355
+ function sameProjection(left: Matrix4, right: Matrix4): boolean {
1356
+ for (const [index, element] of right.elements.entries())
1357
+ if (Math.abs((left.elements[index] as number) - element) > VIEW_EPSILON) return false;
1358
+ return true;
1359
+ }
1360
+
1361
+ /**
1362
+ * A TSL node this module pokes at through the swizzles and the `.element()` chain.
1363
+ *
1364
+ * Three's node types are precise about which swizzle a `vec4` answers and deliberately vague about
1365
+ * what a struct member or an atomic result resolves to, and the kernel is the one place in core
1366
+ * that has to read a struct member and an atomic's return value. The cast is confined here so the
1367
+ * kernel reads as the plain shader it is.
1368
+ */
1369
+ // quality-allow: the kernel is a typed handle onto three's TSL nodes, which resolve to `any` in 0.185.
1370
+ // biome-ignore lint/suspicious/noExplicitAny: three's TSL types refuse the swizzles this kernel reads.
1371
+ type Kernel = Record<string, any>;
1372
+
1373
+ /** `storage(...)` results reach the kernel through this, once. */
1374
+ function nodes(value: unknown): Kernel {
1375
+ return value as Kernel;
1376
+ }
1377
+
1378
+ /** The launch flag. */
1379
+ export const GPU_SCENE_FLAG = "TN_GPU_SCENE";
1380
+
1381
+ /**
1382
+ * Did this launch ask for `flag` to be **off**? The environment variable, the query string and the
1383
+ * global a test sets are the three ways one is asked, and `0` and `false` are the only answers that
1384
+ * count: an unset or empty variable is the same as no variable, and a saved URL that used to enable
1385
+ * a switch still says "off".
1386
+ */
1387
+ function askedOff(flag: string, parameter: string, globalName: string): boolean {
1388
+ const host = globalThis as { process?: { env?: Record<string, unknown> } } & Record<
1389
+ string,
1390
+ unknown
1391
+ >;
1392
+ const fromEnv = host.process?.env?.[flag];
1393
+ if (fromEnv === "0" || fromEnv === "false") return true;
1394
+ const query = globalThis.location?.search;
1395
+ if (
1396
+ typeof query === "string" &&
1397
+ new RegExp(`[?&]${parameter}=(?:0|false)(?:&|$)`, "u").test(query)
1398
+ )
1399
+ return true;
1400
+ const set = host[globalName];
1401
+ return set === false || set === 0 || set === "0" || set === "false";
1402
+ }
1403
+
1404
+ /**
1405
+ * Did this launch ask for `flag` to be **on**? The mirror of {@link askedOff}, for the switches that
1406
+ * are opt-in: the environment variable, the query string and the global a test sets, and only
1407
+ * `1` and `true` count. An unset or empty variable is the same as no variable, so an old URL that
1408
+ * never mentioned the switch stays off.
1409
+ */
1410
+ function askedOn(flag: string, parameter: string, globalName: string): boolean {
1411
+ const host = globalThis as { process?: { env?: Record<string, unknown> } } & Record<
1412
+ string,
1413
+ unknown
1414
+ >;
1415
+ const fromEnv = host.process?.env?.[flag];
1416
+ if (fromEnv === "1" || fromEnv === "true") return true;
1417
+ const query = globalThis.location?.search;
1418
+ if (
1419
+ typeof query === "string" &&
1420
+ new RegExp(`[?&]${parameter}=(?:1|true)(?:&|$)`, "u").test(query)
1421
+ )
1422
+ return true;
1423
+ return host[globalName] === true || host[globalName] === 1 || host[globalName] === "1";
1424
+ }
1425
+
1426
+ /**
1427
+ * Whether the GPU-driven main pass should run on this launch, on by default where the backend can.
1428
+ *
1429
+ * @situation debug a walk whose main pass culls and LOD-selects on the GPU
1430
+ * @constraint on unless a launch asks for the CPU path: `gpuScene: false`, `?tnGpuScene=0` or
1431
+ * `TN_GPU_SCENE=0` turn it off, and a backend without compute, storage buffers and
1432
+ * `drawIndexedIndirect` falls back on its own
1433
+ * @example WorldCells.load({ ...options, gpuScene: gpuSceneRequested() });
1434
+ *
1435
+ * Read the way `renderListValidationRequested` and `terrainValidationRequested` read their own: a
1436
+ * native launch sets the environment variable, a browser asks with the query string, and a test
1437
+ * sets the global. Measured on machinefall at 863f83258, so it flipped from opt-in to default.
1438
+ */
1439
+ export function gpuSceneRequested(): boolean {
1440
+ return askedOff(GPU_SCENE_FLAG, "tnGpuScene", "__tnGpuScene") === false;
1441
+ }
1442
+
1443
+ /** The launch flag. */
1444
+ export const BUNDLE_FLAG = "TN_BUNDLES";
1445
+
1446
+ /**
1447
+ * What this launch asked for about world draw bundles: `on`, `off`, or `default` when it said
1448
+ * nothing.
1449
+ *
1450
+ * @situation tell a run that set the option itself apart from one that took the default
1451
+ * @example WorldCells.load({ ...options, bundles: bundlesAsked() !== "off" });
1452
+ *
1453
+ * Read the way {@link gpuSceneRequested} reads its own: a native launch sets the environment
1454
+ * variable, a browser asks with the query string, and a test sets the global.
1455
+ */
1456
+ export function bundlesAsked(): "default" | "off" | "on" {
1457
+ if (askedOn(BUNDLE_FLAG, "tnBundles", "__tnBundles")) return "on";
1458
+ return askedOff(BUNDLE_FLAG, "tnBundles", "__tnBundles") ? "off" : "default";
1459
+ }
1460
+
1461
+ /**
1462
+ * Whether world draw bundles should be recorded and replayed. On by default, and off unless a launch
1463
+ * asks for the CPU path.
1464
+ *
1465
+ * @situation debug a walk whose main batches are replayed from a recorded bundle
1466
+ * @constraint on unless a launch asks otherwise: `bundles: false`, `?tnBundles=0` or `TN_BUNDLES=0`
1467
+ * turn it off. The default followed a measurement, not a preference — PRD-494 AC-2 took the walking
1468
+ * `draw` span from a 6.0 ms p50 median to 0.6 ms against develop over 3 interleaved runs, on a
1469
+ * picture a blind world gate called equal, so the answer that used to be "off, it gave no CPU
1470
+ * p50/p95 gain" is now "on, it is 5 ms of the walking p95". `bundles: true`, `?tnBundles=1` or
1471
+ * `TN_BUNDLES=1` still say so explicitly. See PRD-473 phase 2 and PRD-494 phase 2.
1472
+ * @example WorldCells.load({ ...options, bundles: bundlesRequested() });
1473
+ */
1474
+ export function bundlesRequested(): boolean {
1475
+ return bundlesAsked() !== "off";
1476
+ }
1477
+
1478
+ /** The validation flag. */
1479
+ export const GPU_SCENE_VALIDATE_FLAG = "TN_GPU_SCENE_VALIDATE";
1480
+
1481
+ /**
1482
+ * Whether the GPU scene should hold every dispatch's indirect args against the CPU reference.
1483
+ *
1484
+ * @situation find the keys a real WebGPU dispatch draws fewer instances of than `cullAndSelect` does
1485
+ * @constraint off by default and never on a measured walk: a readback is a queue submission and a
1486
+ * mapped buffer, so the mode exists to answer "which key" and not to be fast
1487
+ * @example WorldCells.load({ ...options, gpuScene: true, gpuSceneValidate: gpuSceneValidationRequested() });
1488
+ *
1489
+ * Read the way `gpuSceneRequested` reads its own: a native launch sets the environment variable, a
1490
+ * browser asks with `?tnGpuSceneValidate=1`, and a test sets the global.
1491
+ */
1492
+ export function gpuSceneValidationRequested(): boolean {
1493
+ const host = globalThis as {
1494
+ process?: { env?: Record<string, unknown> };
1495
+ __tnGpuSceneValidate?: unknown;
1496
+ };
1497
+ const fromEnv = host.process?.env?.[GPU_SCENE_VALIDATE_FLAG];
1498
+ if (typeof fromEnv === "string" && fromEnv !== "" && fromEnv !== "0" && fromEnv !== "false")
1499
+ return true;
1500
+ const query = globalThis.location?.search;
1501
+ if (
1502
+ typeof query === "string" &&
1503
+ /[?&]tnGpuSceneValidate=(?!0(?:&|$))(?!false(?:&|$))[^&]/u.test(query)
1504
+ )
1505
+ return true;
1506
+ return host.__tnGpuSceneValidate === true || host.__tnGpuSceneValidate === "1";
1507
+ }
1508
+
1509
+ /** The launch flag. */
1510
+ export const SHADOW_GPU_KEYS_FLAG = "TN_SHADOW_GPU_KEYS";
1511
+
1512
+ /**
1513
+ * Whether a shadow level may select its own set of GPU-scene keys. Opt-in, and off by default.
1514
+ *
1515
+ * @situation debug a walk whose shadow maps draw GPU-scene keys instead of cluster meshes
1516
+ * @constraint off unless a launch asks for it: without a provider nothing is allocated and no
1517
+ * dispatch is submitted, so the flag alone cannot change a frame — `shadowGpuKeys: true`,
1518
+ * `?tnShadowGpuKeys=1` or `TN_SHADOW_GPU_KEYS=1` turns it on. See PRD-478 phase 2.
1519
+ * @example world.gpuScene.shadowKeysFrom(() => keyNames);
1520
+ *
1521
+ * Read the way {@link bundlesRequested} reads its own: a native launch sets the environment
1522
+ * variable, a browser asks with the query string, and a test sets the global.
1523
+ */
1524
+ export function shadowGpuKeysRequested(): boolean {
1525
+ return askedOn(SHADOW_GPU_KEYS_FLAG, "tnShadowGpuKeys", "__tnShadowGpuKeys");
1526
+ }
1527
+
1528
+ /**
1529
+ * The GPU scene, owned by one `WorldCells`.
1530
+ *
1531
+ * The buffers exist once, and a capacity change replaces the attribute and the kernel with it — a
1532
+ * structural event, on the same cadence as a key being minted. Between two of them the per-frame
1533
+ * cost is one dispatch and six plane writes.
1534
+ */
1535
+ export class WorldGpuScene {
1536
+ /** Resident placements, in the source buffer's own order; index 0 is the buffer's first record. */
1537
+ readonly placements: IGpuPlacement[] = [];
1538
+ readonly #regions: IRegion[] = [];
1539
+ readonly #keysByName = new Map<string, number>();
1540
+ /**
1541
+ * The shadow twins, allocated only once a provider has registered: their own args records and
1542
+ * their own drawn runs, and the keys that hold them. A twin of a key is its own record and run in
1543
+ * these buffers, at the layout the key already has — the main pass cannot have them, because its
1544
+ * compute submits before its indirect draws and a shared record would be zeroed in between.
1545
+ */
1546
+ #shadow: IShadowBuffers | undefined;
1547
+ #shadowProvider: (() => Iterable<string>) | undefined;
1548
+ #shadowKernel: { readonly cull: unknown; readonly clear: unknown } | undefined;
1549
+ readonly #slotsByAsset = new Map<string, IAssetSlot>();
1550
+ /** One level's parts per `asset:level`, which is what keeps them the run the kernel addresses. */
1551
+ readonly #groups = new Map<string, ILevelGroup>();
1552
+ /** Slot order, so a slot index is a position the `gates` buffer and the reference agree on. */
1553
+ readonly #order: string[] = [];
1554
+ /** Source records whose cell has left the ring, handed back before the buffer grows. */
1555
+ readonly #free: number[] = [];
1556
+ #buffers: IGpuSceneBuffers | undefined;
1557
+ #dispatched = 0;
1558
+ #drawnCapacity = 0;
1559
+ #live = 0;
1560
+ #on = false;
1561
+ #reason = "not-attached";
1562
+ /** Set by the one report this class ever prints, so a frame cannot repeat the line. */
1563
+ #reported = false;
1564
+ /** Bumped by every buffer swap, so a mesh re-dressed once knows if it still points at live data. */
1565
+ #version = 0;
1566
+ /** The kernel, rebuilt whenever a capacity changed under it. */
1567
+ #kernel: { readonly cull: unknown; readonly clear: unknown } | undefined;
1568
+ #planes = new Float32Array(24);
1569
+
1570
+ /**
1571
+ * Turn the GPU scene on if this backend can run it, and say why not when it cannot. One line,
1572
+ * once, and never silent. `validate` holds every dispatch's args against the CPU reference; see
1573
+ * {@link gpuSceneValidationRequested}.
1574
+ */
1575
+ enable(
1576
+ renderer: IRendererLike | undefined,
1577
+ wanted: boolean,
1578
+ validate = false,
1579
+ tally = false,
1580
+ occlusion: OcclusionMode = "off",
1581
+ ): boolean {
1582
+ this.#validate = validate;
1583
+ this.#tally = tally || occlusion !== "off";
1584
+ this.#occlusion = occlusion;
1585
+ if (this.#on) return true;
1586
+ if (this.#reported) return false;
1587
+ if (renderer === undefined) {
1588
+ this.#reason = "no-renderer";
1589
+ return false;
1590
+ }
1591
+ if (wanted === false) {
1592
+ this.#reason = "option-off";
1593
+ this.#report(renderer);
1594
+ return false;
1595
+ }
1596
+ const unsupported = gpuSceneUnsupported(renderer);
1597
+ if (unsupported !== "") {
1598
+ this.#reason = unsupported;
1599
+ this.#report(renderer);
1600
+ return false;
1601
+ }
1602
+ this.#on = true;
1603
+ this.#reason = "on";
1604
+ this.#watchDevice(renderer);
1605
+ // Not printed here: the owner's own line is the one that says how many of its meshes are
1606
+ // dressed, and that number is only known once it has dressed them — see {@link announce}.
1607
+ return true;
1608
+ }
1609
+
1610
+ /**
1611
+ * The one line, printed once, with the owner's census of dressed main meshes.
1612
+ *
1613
+ * `enable` announces every answer but "on", because a scene that is off has nothing to count. This
1614
+ * is the answer that does: the owner dresses the keys a ring built before the scene came up is
1615
+ * already holding, and only then can `dressed=N/M` say whether the dispatch has anything to draw
1616
+ * into. A caller with no owner of its own announces without a census, which reads `0/0`.
1617
+ */
1618
+ announce(
1619
+ renderer: IRendererLike,
1620
+ census?: { readonly dressed: number; readonly meshes: number },
1621
+ ): void {
1622
+ if (census !== undefined) this.#census = { dressed: census.dressed, meshes: census.meshes };
1623
+ this.#report(renderer);
1624
+ }
1625
+
1626
+ /**
1627
+ * Hold the device's uncaptured errors, so a check can read them instead of the console.
1628
+ *
1629
+ * Three already chains its own `onuncapturederror` onto the same device and prints the message,
1630
+ * which is the whole reason a refused pipeline reads as a healthy run: the evidence was on screen
1631
+ * as a console line nothing compared against the counts. This wraps that handler rather than
1632
+ * replacing it, so three's own reporting still fires, and the last message is folded into the next
1633
+ * `TN_WORLD_GPU_SCENE_VALIDATE` line. Nothing is cleared except by a check that has reported it,
1634
+ * so an error that arrives between two checks still lands on the one after.
1635
+ */
1636
+ #watchDevice(renderer: IRendererLike): void {
1637
+ const device = (renderer.raw as { backend?: { device?: IDeviceLike } })?.backend?.device;
1638
+ if (device === undefined || this.#watched) return;
1639
+ this.#watched = true;
1640
+ const previous = device.onuncapturederror;
1641
+ device.onuncapturederror = (event: unknown): void => {
1642
+ this.#deviceError = uncapturedMessage(event);
1643
+ if (typeof previous === "function") previous.call(device, event);
1644
+ };
1645
+ }
1646
+
1647
+ get on(): boolean {
1648
+ return this.#on;
1649
+ }
1650
+
1651
+ /**
1652
+ * Bumped by every structural change — a key minted, retired or regrown, any buffer grown — so the
1653
+ * main meshes know their `instanceMatrix` and `setIndirect` may be pointing at a buffer the scene
1654
+ * has since replaced. It only moves on a structural event, so a settled frame never re-dresses.
1655
+ */
1656
+ get version(): number {
1657
+ return this.#version;
1658
+ }
1659
+
1660
+ /** The shared compacted matrix buffer every main batch's `instanceMatrix` is. */
1661
+ get drawn(): StorageInstancedBufferAttribute | undefined {
1662
+ return this.#buffers?.drawn;
1663
+ }
1664
+
1665
+ /** The one indirect record buffer every main key's `setIndirect` points into. */
1666
+ get args(): IndirectStorageBufferAttribute | undefined {
1667
+ return this.#buffers?.args;
1668
+ }
1669
+
1670
+ /** The twin of {@link drawn}, once a provider has registered: a shadow key's `instanceMatrix`. */
1671
+ get shadowDrawn(): StorageInstancedBufferAttribute | undefined {
1672
+ return this.#shadow?.drawn;
1673
+ }
1674
+
1675
+ /** The twin of {@link args}, once a provider has registered: a shadow key's indirect record. */
1676
+ get shadowArgs(): IndirectStorageBufferAttribute | undefined {
1677
+ return this.#shadow?.args;
1678
+ }
1679
+
1680
+ /**
1681
+ * Every storage buffer with the WGSL type the kernel binds it as, so the allocation can be held
1682
+ * against the declaration without reading a pipeline.
1683
+ *
1684
+ * WebGPU refuses a bind whose buffer is under one element of its declared type, and the refusal is
1685
+ * an uncaptured validation error: the dispatch is invalid, the counts stay whatever the clear pass
1686
+ * wrote, and nothing downstream of it is measurable. The check is here because a run proved the
1687
+ * other way that a validation line reading `ok` over a kernel that had never run is worth less than
1688
+ * no line at all.
1689
+ */
1690
+ footprint(): Record<string, IGpuSceneBufferFootprint> {
1691
+ const out: Record<string, IGpuSceneBufferFootprint> = {};
1692
+ if (this.#buffers === undefined) return out;
1693
+ for (const [name, type] of [
1694
+ ...Object.entries(STORAGE_PLAIN),
1695
+ ["args", "uint"],
1696
+ ["drawn", "mat4"],
1697
+ ] as [BufferName, StorageType][]) {
1698
+ const buffer = this.#buffers[name] as BufferAttribute;
1699
+ out[name] = { type, count: buffer.count, bytes: buffer.array.byteLength };
1700
+ }
1701
+ // The twins only exist once a provider has registered, so a launch that never asked for them
1702
+ // reads exactly the footprint it had before this class learned about shadows.
1703
+ if (this.#shadow !== undefined) {
1704
+ out.shadowArgs = {
1705
+ type: "uint",
1706
+ count: this.#shadow.args.count,
1707
+ bytes: this.#shadow.args.array.byteLength,
1708
+ };
1709
+ out.shadowDrawn = {
1710
+ type: "mat4",
1711
+ count: this.#shadow.drawn.count,
1712
+ bytes: this.#shadow.drawn.array.byteLength,
1713
+ };
1714
+ }
1715
+ return out;
1716
+ }
1717
+
1718
+ report(): IWorldGpuSceneReport {
1719
+ return {
1720
+ dispatches: this.#dispatched,
1721
+ instances: this.#live,
1722
+ keys: this.#regions.length,
1723
+ on: this.#on,
1724
+ reason: this.#reason,
1725
+ // Absent until a sample lands, never zero: "the GPU selected nothing" and "nothing has been
1726
+ // read back yet" are different facts, and a zero would merge them.
1727
+ ...(this.#tallySample < 0
1728
+ ? {}
1729
+ : {
1730
+ gpuInstances: this.#tallyInstances,
1731
+ gpuTallyAgeFrames: this.#dispatched - this.#tallySample,
1732
+ gpuTriangles: this.#tallyTriangles,
1733
+ }),
1734
+ ...(this.#occlusion === "off"
1735
+ ? {}
1736
+ : {
1737
+ occlusion: {
1738
+ ageFrames: this.#occlusionSample < 0 ? 0 : this.#dispatched - this.#occlusionSample,
1739
+ buildDispatches: this.#pyramid.levels,
1740
+ instances: this.#occludedInstances,
1741
+ levels: this.#pyramid.levels,
1742
+ meanInstances:
1743
+ this.#occlusionSamples === 0
1744
+ ? 0
1745
+ : Math.round(this.#occlusionSumInstances / this.#occlusionSamples),
1746
+ meanTriangles:
1747
+ this.#occlusionSamples === 0
1748
+ ? 0
1749
+ : Math.round(this.#occlusionSumTriangles / this.#occlusionSamples),
1750
+ mode: this.#occlusion,
1751
+ reason: this.#occlusionReason,
1752
+ samples: this.#occlusionSamples,
1753
+ gpuTriangles: this.#occlusionTotalTriangles,
1754
+ share:
1755
+ this.#occlusionTotalTriangles === 0
1756
+ ? 0
1757
+ : this.#occludedTriangles / this.#occlusionTotalTriangles,
1758
+ triangles: this.#occludedTriangles,
1759
+ },
1760
+ }),
1761
+ };
1762
+ }
1763
+
1764
+ /**
1765
+ * The main pass's one key per `asset:level:part`: give it a region of the drawn buffer and an args
1766
+ * record, or hand back the ones it already has.
1767
+ *
1768
+ * A region is assigned once and never moves its args record, because `firstInstance` is written
1769
+ * into that record on the CPU and read by the draw. A key that outgrew its region is regrown into
1770
+ * a larger one at the tail, which is the only structural change a walk makes — and a key that is
1771
+ * one of a level's parts is regrown with its siblings, because the kernel addresses a level's parts
1772
+ * as one contiguous run and a part that moved alone would break that run. See {@link levelKeys}.
1773
+ */
1774
+ key(name: string, local: Float32Array, capacity: number, level?: ILevelKey): number | undefined {
1775
+ if (level !== undefined) return this.#levelKey(name, local, capacity, level);
1776
+ const existing = this.#keysByName.get(name);
1777
+ if (existing !== undefined) {
1778
+ const region = this.#regions[existing] as IRegion;
1779
+ if (region.capacity >= capacity) return existing;
1780
+ // A regrow: the old region is abandoned, the new one is the tail, and the args record's
1781
+ // `firstInstance` moves with it. Structural, so a bundle version may be bumped for it.
1782
+ this.#keysByName.set(name, this.#regions.length);
1783
+ this.#regions.push({ ...region, name, start: this.#drawnCapacity, capacity });
1784
+ this.#drawnCapacity += capacity;
1785
+ const regrown = this.#regions.length - 1;
1786
+ this.#growOf("keys", regrown + 1);
1787
+ this.#growOf("locals", regrown + 1);
1788
+ this.#growOf("args", argsWords(regrown + 1));
1789
+ this.#growDrawn();
1790
+ this.#writeKey(this.#regions.length - 1);
1791
+ return this.#regions.length - 1;
1792
+ }
1793
+ this.#ensure();
1794
+ const index = this.#mintRegion(name, local, capacity);
1795
+ this.#keysByName.set(name, index);
1796
+ return index;
1797
+ }
1798
+
1799
+ /**
1800
+ * One region at the tail of the key index space, with its own args record and its own drawn run,
1801
+ * and every buffer wide enough to name it.
1802
+ *
1803
+ * The key index, the args record and the drawn run all move together here. A part that takes a
1804
+ * claimed slot replaces the region already standing there rather than pushing a new one, so it
1805
+ * inherits the args record the slot was written against and no geometry's indirect offset moves.
1806
+ */
1807
+ #mintRegion(name: string, local: Float32Array, capacity: number): number {
1808
+ const index = this.#regions.length;
1809
+ this.#regions.push({
1810
+ argsIndex: index,
1811
+ capacity,
1812
+ indexCount: 0,
1813
+ local,
1814
+ name,
1815
+ start: this.#drawnCapacity,
1816
+ });
1817
+ this.#drawnCapacity += capacity;
1818
+ this.#growOf("keys", index + 1);
1819
+ this.#growOf("locals", index + 1);
1820
+ this.#growOf("args", argsWords(index + 1));
1821
+ this.#growDrawn();
1822
+ this.#writeKey(index);
1823
+ return index;
1824
+ }
1825
+
1826
+ /**
1827
+ * One part of a level, in the level's own run: minted into the slot `firstKey + part` names, and
1828
+ * regrown with its siblings.
1829
+ *
1830
+ * The run is what makes `firstKey + part` mean the right key, so it is claimed whole at the level's
1831
+ * first key and read back through {@link levelKeys} rather than by the caller remembering which
1832
+ * index it saw first. A part of the level nothing has asked for yet holds its slot as a
1833
+ * capacity-zero region: the gate table names the whole run, the kernel reads a part's capacity
1834
+ * before it writes into it, and a part with no mesh draws nothing at its own index. Each part
1835
+ * keeps its own args record, so minting a later part re-lays no indirect offset and re-dresses no
1836
+ * mesh.
1837
+ */
1838
+ #levelKey(
1839
+ name: string,
1840
+ local: Float32Array,
1841
+ capacity: number,
1842
+ level: ILevelKey,
1843
+ ): number | undefined {
1844
+ if (this.#ensure() === undefined) return undefined;
1845
+ let held = this.#groups.get(level.group);
1846
+ if (held === undefined) {
1847
+ held = {
1848
+ capacity,
1849
+ firstKey: this.#regions.length,
1850
+ minted: new Map<number, number>(),
1851
+ parts: level.parts,
1852
+ };
1853
+ this.#groups.set(level.group, held);
1854
+ for (let part = 0; part < level.parts; part += 1)
1855
+ this.#mintRegion(`${level.group}:${String(part)}`, NO_LOCAL, 0);
1856
+ }
1857
+ // A part the level did not declare is refused rather than laid over the next level's key, which
1858
+ // is the one mistake this method exists to stop.
1859
+ if (level.part >= held.parts) return undefined;
1860
+ const index = held.firstKey + level.part;
1861
+ const opened = held.minted.has(level.part) === false;
1862
+ const grew = capacity > held.capacity;
1863
+ if (grew) held.capacity = capacity;
1864
+ // A part already laid out at this capacity keeps its run: registering it again is not a
1865
+ // structural change. Laying the level out again appended the whole group to the tail of the drawn
1866
+ // buffer every call, so a frame that only re-dressed the ring grew the buffer by the level, the
1867
+ // next frame's re-dress grew it by the level again, and the buffer doubled until the device
1868
+ // refused the allocation. Only opening a part or outgrowing the capacity moves the run.
1869
+ if (opened === false && grew === false) {
1870
+ const settled = this.#regions[index] as IRegion;
1871
+ this.#keysByName.set(name, index);
1872
+ // A fresh `Float32Array` of the same offset is the same offset: a re-dress copies the part's
1873
+ // matrix out each time, so comparing identity would re-upload the key table for nothing.
1874
+ if (settled.name !== name || sameLocal(settled.local, local) === false) {
1875
+ this.#regions[index] = { ...settled, local, name };
1876
+ this.#writeKey(index);
1877
+ }
1878
+ return index;
1879
+ }
1880
+ const slot = this.#regions[index] as IRegion;
1881
+ this.#keysByName.set(name, index);
1882
+ this.#regions[index] = {
1883
+ argsIndex: index,
1884
+ capacity: held.capacity,
1885
+ indexCount: slot.indexCount,
1886
+ local,
1887
+ name,
1888
+ start: slot.start,
1889
+ };
1890
+ held.minted.set(level.part, index);
1891
+ // A structural change re-packs every run from zero, so the buffer is bounded by the runs that
1892
+ // exist rather than by every run ever abandoned in a relocation. See {@link #relayout}.
1893
+ this.#drawnCapacity = this.#relayout();
1894
+ this.#growDrawn();
1895
+ // The live buffers, not the ones this method read: a regrow above may have replaced them.
1896
+ this.#writeAllKeys();
1897
+ return index;
1898
+ }
1899
+
1900
+ /**
1901
+ * The keys one level's parts draw into, which is what the gate table needs and the kernel assumes.
1902
+ *
1903
+ * The run the level claimed, read back rather than measured off the parts that happen to be
1904
+ * minted: measuring it is what let another level's keys inside a run whose parts were minted apart.
1905
+ */
1906
+ levelKeys(group: string): { readonly firstKey: number; readonly parts: number } | undefined {
1907
+ const held = this.#groups.get(group);
1908
+ if (held === undefined || held.minted.size === 0) return undefined;
1909
+ return { firstKey: held.firstKey, parts: held.parts };
1910
+ }
1911
+
1912
+ /**
1913
+ * Pack every region from the front of the drawn buffer, answering where it now ends.
1914
+ *
1915
+ * A level that opens a part or outgrows its capacity needs a new run, and appending only that level
1916
+ * at the tail left its old run behind: a walk that streamed for a while relocated the same levels
1917
+ * over and over, and the drawn buffer grew by every abandoned run until the device refused the
1918
+ * allocation. Packing every region from zero on a structural change keeps the buffer bounded by the
1919
+ * runs that exist — the sum of each level's own run, which is what a resident world holds.
1920
+ *
1921
+ * Non-grouped keys keep their order and their own capacity first; a level's parts follow together
1922
+ * in part order, which is the run the kernel addresses as `firstKey + part`. Unminted parts hold a
1923
+ * capacity-zero slot and take no room.
1924
+ */
1925
+ #relayout(): number {
1926
+ const grouped = new Set<number>();
1927
+ for (const held of this.#groups.values())
1928
+ for (let part = 0; part < held.parts; part += 1) grouped.add(held.firstKey + part);
1929
+ let start = 0;
1930
+ for (const [index, region] of this.#regions.entries()) {
1931
+ if (grouped.has(index)) continue;
1932
+ region.start = start;
1933
+ start += region.capacity;
1934
+ }
1935
+ for (const held of this.#groups.values()) {
1936
+ const ordered = [...held.minted.entries()].sort((one, other) => one[0] - other[0]);
1937
+ for (const [, index] of ordered) {
1938
+ const region = this.#regions[index] as IRegion;
1939
+ region.start = start;
1940
+ region.capacity = held.capacity;
1941
+ start += held.capacity;
1942
+ }
1943
+ }
1944
+ return start;
1945
+ }
1946
+
1947
+ /**
1948
+ * Re-write every key's gate and args record, which a re-layout moved, against the live buffers —
1949
+ * a grow inside the layout may have replaced them, so the set the caller held is not the one a
1950
+ * draw and the kernel will read.
1951
+ */
1952
+ #writeAllKeys(): void {
1953
+ for (let index = 0; index < this.#regions.length; index += 1) this.#writeKey(index);
1954
+ }
1955
+
1956
+ /** The region one key draws from, for the counters and the tests. */
1957
+ regionOf(name: string): IRegion | undefined {
1958
+ const index = this.#keysByName.get(name);
1959
+ return index === undefined ? undefined : this.#regions[index];
1960
+ }
1961
+
1962
+ /**
1963
+ * The index count the dressed geometry draws with, recorded against the key the owner dressed.
1964
+ *
1965
+ * A `DrawIndexedIndirect` record names no triangles at all when its `indexCount` is zero, and the
1966
+ * scene cannot know what shape a key draws: the owner holds the geometry. So the owner says, and
1967
+ * the validation holds the record against what it said — a draw that is submitted, counted, and
1968
+ * draws nothing is the one failure a count cannot see.
1969
+ */
1970
+ indexCount(name: string, count: number): void {
1971
+ const index = this.#keysByName.get(name);
1972
+ if (index === undefined) return;
1973
+ (this.#regions[index] as IRegion).indexCount = count;
1974
+ // The record is what the GPU draws from: a count kept only for validation left every indirect
1975
+ // draw at `indexCount` 0, submitted and counted, drawing nothing.
1976
+ this.#writeKey(index);
1977
+ }
1978
+
1979
+ /**
1980
+ * The gates one asset's levels are crossed at, registered the first time any of its keys is
1981
+ * minted. Distances and cull distance are the CPU path's own numbers, so the same placement
1982
+ * reaches the same level wherever the level is decided.
1983
+ */
1984
+ slot(asset: string, definition: IAssetSlot): number {
1985
+ const at = this.#order.indexOf(asset);
1986
+ if (at >= 0 && sameGates(this.#slotsByAsset.get(asset) as IAssetSlot, definition)) return at;
1987
+ if (this.#ensure() === undefined) return SLOT_NONE;
1988
+ this.#slotsByAsset.set(asset, definition);
1989
+ if (at < 0) this.#order.push(asset);
1990
+ this.#writeSlots();
1991
+ return at < 0 ? this.#order.length - 1 : at;
1992
+ }
1993
+
1994
+ /** The gates a slot index names, which is what the kernel and the reference both read. */
1995
+ gates(): readonly IAssetSlot[] {
1996
+ return this.#order.map((asset) => this.#slotsByAsset.get(asset) as IAssetSlot);
1997
+ }
1998
+
1999
+ /**
2000
+ * The asset id a slot index names, which is how the owner looks its own live gates up.
2001
+ *
2002
+ * The identity and nothing else: no distance, no cull, no level — the check that must not read
2003
+ * this class's tables gets its numbers from the owner and comes here only for the name of the
2004
+ * asset a placement belongs to, which the placement itself does not carry.
2005
+ */
2006
+ slotAsset(slot: number): string | undefined {
2007
+ return this.#order[slot];
2008
+ }
2009
+
2010
+ /** The regions the keys own, in key order, which is what the kernel's `keys` buffer holds. */
2011
+ get regions(): readonly IRegion[] {
2012
+ return this.#regions;
2013
+ }
2014
+
2015
+ /**
2016
+ * Take a source record for one placement, or `undefined` when the buffer is full. A record is
2017
+ * 24 words: the world matrix, the sphere and the asset slot, which is everything the kernel reads.
2018
+ */
2019
+ place(
2020
+ asset: number,
2021
+ matrix: Matrix4,
2022
+ x: number,
2023
+ y: number,
2024
+ z: number,
2025
+ radius: number,
2026
+ scale = 1,
2027
+ ): number {
2028
+ const reused = this.#free.pop();
2029
+ const index = reused ?? this.placements.length;
2030
+ if (reused === undefined && this.#reserve(index + 1) === false) return -1;
2031
+ let placement = this.placements[index];
2032
+ if (placement === undefined) {
2033
+ placement = {
2034
+ centre: new Float32Array(4),
2035
+ matrix: new Float32Array(LOCAL_WORDS),
2036
+ scale: 1,
2037
+ slot: SLOT_NONE,
2038
+ };
2039
+ this.placements[index] = placement;
2040
+ }
2041
+ placement.matrix.set(matrix.elements);
2042
+ placement.centre[0] = x;
2043
+ placement.centre[1] = y;
2044
+ placement.centre[2] = z;
2045
+ placement.centre[3] = radius;
2046
+ placement.slot = asset;
2047
+ placement.scale = Number.isFinite(scale) ? scale : 1;
2048
+ this.#live += 1;
2049
+ this.#writePlacement(index);
2050
+ return index;
2051
+ }
2052
+
2053
+ /** Hand a source record back; the kernel skips a released one and the slot is reused. */
2054
+ release(index: number): void {
2055
+ const placement = this.placements[index];
2056
+ if (placement === undefined || placement.slot < 0) return;
2057
+ placement.slot = SLOT_NONE;
2058
+ this.#live -= 1;
2059
+ this.#free.push(index);
2060
+ this.#writePlacement(index);
2061
+ }
2062
+
2063
+ /**
2064
+ * Sets the adaptive LOD bias the kernel scales camera distance by, `>= 1`. The shared CPU
2065
+ * `setLodBias` holds the same number; `WorldCells` writes both. A non-finite or below-1 value is
2066
+ * no reading and resets to 1, matching the CPU clamp.
2067
+ */
2068
+ setLodBias(bias: number): void {
2069
+ this.#lodBias.value = Number.isFinite(bias) && bias >= 1 ? bias : 1;
2070
+ }
2071
+
2072
+ /**
2073
+ * Register who owns the shadow keys. Until something does, nothing is allocated and
2074
+ * {@link dispatchShadow} submits nothing.
2075
+ *
2076
+ * The provider is asked for the keys a shadow map draws at dispatch time rather than once here, so
2077
+ * a key minted after the registration is a twin of the same pass that first needs it. It names the
2078
+ * keys, not their contents: a twin is its main key's record and run in the twin buffers, at the
2079
+ * layout that key already holds.
2080
+ *
2081
+ * A launch without `?tnShadowGpuKeys=1` (or the environment variable, or the global) registers
2082
+ * nothing, so the flag alone cannot put a buffer on the device. See {@link shadowGpuKeysRequested}.
2083
+ */
2084
+ shadowKeysFrom(provider: () => Iterable<string>): void {
2085
+ if (shadowGpuKeysRequested() === false) return;
2086
+ this.#shadowProvider = provider;
2087
+ }
2088
+
2089
+ /** Whether a provider has registered, which is the whole of what turns the shadow path on. */
2090
+ get shadowKeys(): boolean {
2091
+ return this.#shadowProvider !== undefined;
2092
+ }
2093
+
2094
+ /**
2095
+ * Name one key's shadow twin now, rather than waiting for the dispatch that first needs it: the
2096
+ * mesh that draws it has to be dressed against a record that exists, and a record minted inside
2097
+ * the render it would draw in is one frame late for every key.
2098
+ *
2099
+ * The same {@link #mintShadowKeys} the dispatch runs, for one name — idempotent, and a no-op
2100
+ * without a registered provider, which is what keeps the flag from allocating anything on its own.
2101
+ */
2102
+ shadowKey(name: string): void {
2103
+ if (this.#shadowProvider === undefined) return;
2104
+ this.#mintShadowKeys([name]);
2105
+ }
2106
+
2107
+ /** The region one key's shadow twin draws from, for the counters and the tests. */
2108
+ shadowRegionOf(name: string): IRegion | undefined {
2109
+ const index = this.#shadow?.keys.get(name);
2110
+ return index === undefined ? undefined : this.#regions[index];
2111
+ }
2112
+
2113
+ /**
2114
+ * One shadow level's set: zero every twin's instance count, then cull and LOD-select every resident
2115
+ * placement against the map's own light frustum, the main pass's eye and level, its texel gate
2116
+ * and the chain level it draws at — into the twin buffers, which the main pass cannot be holding.
2117
+ *
2118
+ * The twin of the main kernel branch for branch, and reading the main pass's own gate table,
2119
+ * placements and key table: a shadow map draws the same shapes, only a different set of them.
2120
+ * A no-op without a registered provider, which is the only way this can be switched on.
2121
+ */
2122
+ dispatchShadow(renderer: IRendererLike, level: IShadowLevel): void {
2123
+ const provider = this.#shadowProvider;
2124
+ if (provider === undefined || this.#on === false || this.#buffers === undefined) return;
2125
+ // Minted here, so a twin is never older than the key it twins; the growth is a structural event
2126
+ // and the kernel below is rebuilt against the buffers that replaced the old ones.
2127
+ this.#mintShadowKeys(provider());
2128
+ const kernel = this.#shadowKernel ?? this.#buildShadowKernel();
2129
+ if (kernel === undefined) return;
2130
+ for (const [index, plane] of this.#shadowPlaneVectors.entries()) {
2131
+ const at = index * 4;
2132
+ plane.set(
2133
+ level.planes[at] as number,
2134
+ level.planes[at + 1] as number,
2135
+ level.planes[at + 2] as number,
2136
+ level.planes[at + 3] as number,
2137
+ );
2138
+ }
2139
+ this.#shadowGate.value = level.gate;
2140
+ this.#shadowBase.value = level.base;
2141
+ // `(placements, slots, keys, keys)`: the last two are the same count, and the clear dispatch is
2142
+ // one thread per key. The main pass writes the same uniform before its own pair.
2143
+ const keys = this.#regions.length;
2144
+ this.#counts.value.set(this.placements.length, this.#order.length, keys, keys);
2145
+ // One pass holds both kernels: storage writes reach the next dispatch, so clear precedes cull.
2146
+ renderer.compute([kernel.clear, kernel.cull]);
2147
+ }
2148
+
2149
+ /**
2150
+ * One frame of the main pass: zero every key's instance count, then cull and LOD-select every
2151
+ * resident placement into the shared drawn buffer. Nothing else is written.
2152
+ */
2153
+ dispatch(renderer: IRendererLike, camera: Camera): void {
2154
+ if (this.#on === false) return;
2155
+ if (this.#buffers === undefined) return;
2156
+ cameraPlanes(camera, this.#planes);
2157
+ for (const [index, plane] of this.#planeVectors.entries()) {
2158
+ const at = index * 4;
2159
+ plane.set(
2160
+ this.#planes[at] as number,
2161
+ this.#planes[at + 1] as number,
2162
+ this.#planes[at + 2] as number,
2163
+ this.#planes[at + 3] as number,
2164
+ );
2165
+ }
2166
+ _eye.setFromMatrixPosition(camera.matrixWorld);
2167
+ this.#eye.value.copy(_eye);
2168
+ // `(placements, slots, keys, keys)`: the last two are the same count, and the clear dispatch is
2169
+ // one thread per key.
2170
+ if (this.#occlusion !== "off") this.#measureOcclusion(renderer, camera);
2171
+ // Measurement may replace the pyramid buffer on first use or resize. Bind the new buffer in
2172
+ // this frame's cull, rather than dispatching a kernel captured before the replacement.
2173
+ const kernel = this.#kernel ?? this.#buildKernel();
2174
+ if (kernel === undefined) return;
2175
+ const keys = this.#regions.length;
2176
+ this.#counts.value.set(this.placements.length, this.#order.length, keys, keys);
2177
+ // One pass holds both kernels: storage writes reach the next dispatch, so clear precedes cull.
2178
+ renderer.compute([kernel.clear, kernel.cull]);
2179
+ this.#dispatched += 1;
2180
+ if (
2181
+ this.#validate === true &&
2182
+ this.#manualOnly === false &&
2183
+ this.#validating === false &&
2184
+ this.#dispatched % VALIDATE_EVERY === 0
2185
+ )
2186
+ this.#compare(renderer);
2187
+ // A validation's own readback already holds the args, so it feeds the tally and this never adds
2188
+ // a second copy beside it. With validation off the tally reads on its own slower clock, and a
2189
+ // frame whose predecessor has not landed is skipped rather than queued.
2190
+ else if (
2191
+ this.#validate === false &&
2192
+ this.#tally === true &&
2193
+ (this.#occlusion === "off" || this.#occlusionCut.value === 0) &&
2194
+ this.#tallyPending === false &&
2195
+ (this.#tallyRequested < 0 || this.#dispatched - this.#tallyRequested >= TALLY_EVERY)
2196
+ )
2197
+ this.#tallyRead(renderer);
2198
+ }
2199
+
2200
+ /**
2201
+ * One frame of `?tnOcclusion=measure`: rebuild the max-distance chain from the depth the previous
2202
+ * frame's scene pass left behind, and point the test at the camera that depth was rendered with.
2203
+ *
2204
+ * The depth is last frame's on purpose. This runs in `beforeRender`, before the frame's own scene
2205
+ * pass draws, so the texture still holds what the last one wrote — which is the only depth there
2206
+ * is, and the reason the test reprojects rather than sampling the current frame.
2207
+ *
2208
+ * With no scene-pass depth — no render chain installed, so nothing rendered into a target of its
2209
+ * own — the mode refuses and says so in `report().occlusion.reason` rather than reporting nothing
2210
+ * hidden and reading as a cull that found no work.
2211
+ */
2212
+ #measureOcclusion(renderer: IRendererLike, camera: Camera): void {
2213
+ this.#occlusionCut.value = 1;
2214
+ // The main pass returns on an orthographic camera before it gets here (that is a shadow level's
2215
+ // own), and a linear depth in metres is a perspective projection's to begin with.
2216
+ if (!(camera instanceof PerspectiveCamera)) {
2217
+ this.#previousDepth = undefined;
2218
+ this.#occlusionReason = "refused: not a perspective camera";
2219
+ return;
2220
+ }
2221
+ const raw = renderer.raw as { logarithmicDepthBuffer?: boolean; reversedDepthBuffer?: boolean };
2222
+ if (raw?.logarithmicDepthBuffer || raw?.reversedDepthBuffer || camera.reversedDepth) {
2223
+ this.#previousDepth = undefined;
2224
+ this.#occlusionReason = "refused: nonstandard depth";
2225
+ return;
2226
+ }
2227
+ const depth = renderer.scenePassDepth?.();
2228
+ const width = depth?.width ?? 0;
2229
+ const height = depth?.height ?? 0;
2230
+ if (depth === undefined || width < 2 || height < 2) {
2231
+ this.#previousDepth = undefined;
2232
+ this.#occlusionReason = "refused: no scene depth";
2233
+ return;
2234
+ }
2235
+ this.#occlusionReason = "";
2236
+ // A resized depth resizes the chain, and the chain's two buffers are what the cull kernel reads,
2237
+ // so a new chain is a new pipeline: structural, like every other grow in this class.
2238
+ const resized = this.#pyramid.resize(width, height);
2239
+ if (resized) {
2240
+ this.#kernel = undefined;
2241
+ this.#version += 1;
2242
+ }
2243
+ _view.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
2244
+ _eye.setFromMatrixPosition(camera.matrixWorld);
2245
+ // A cut skips the test for the frame: a teleport moved the camera further than a walk step, and
2246
+ // a projection change means the pyramid is a different camera's depth altogether.
2247
+ // ponytail: 2 m of camera travel in one dispatch is a cut. A game that teleports further per
2248
+ // step than that raises the bound; one that cuts under it gets a frame of frustum-only.
2249
+ const samples = depth.samples ?? 1;
2250
+ const previous = this.#previousDepth;
2251
+ const depthChanged =
2252
+ previous?.texture !== depth.texture ||
2253
+ previous.width !== width ||
2254
+ previous.height !== height ||
2255
+ previous.samples !== samples ||
2256
+ previous.version !== depth.texture.version;
2257
+ this.#occlusionCut.value =
2258
+ depthChanged ||
2259
+ resized ||
2260
+ !sameProjection(this.#previousProjection, camera.projectionMatrix) ||
2261
+ _eye.distanceTo(this.#previousEye) > OCCLUSION_CUT_METRES
2262
+ ? 1
2263
+ : 0;
2264
+ if (this.#occlusionCut.value !== 0)
2265
+ this.#occlusionReason =
2266
+ depthChanged || resized ? "skipped: depth changed" : "skipped: camera cut";
2267
+ this.#previousDepth = {
2268
+ texture: depth.texture,
2269
+ width,
2270
+ height,
2271
+ samples,
2272
+ version: depth.texture.version,
2273
+ };
2274
+ this.#previousProjection.copy(camera.projectionMatrix);
2275
+ // The chain first, then the camera the chain belongs to: last frame's, which is what the
2276
+ // previous frame's depth recorded.
2277
+ this.#pyramid.build(renderer, depth.texture, camera.near, camera.far, samples);
2278
+ this.#occlusionView.value.copy(this.#previousView);
2279
+ this.#previousView.copy(_view);
2280
+ this.#previousEye.copy(_eye);
2281
+ }
2282
+
2283
+ /**
2284
+ * What the last landed readback found, so a harness can read the answer without the log: the
2285
+ * verdict, how many keys it actually compared, how many disagreed on the count, how many on what
2286
+ * the draw reads, how many dressed meshes drew instances their own key never owned, and the lines.
2287
+ */
2288
+ get validation(): {
2289
+ readonly verdict: GpuSceneVerdict;
2290
+ readonly compared: number;
2291
+ readonly mismatched: number;
2292
+ readonly matricesMismatched: number;
2293
+ readonly meshMismatched: number;
2294
+ readonly lines: readonly string[];
2295
+ } {
2296
+ return {
2297
+ verdict: this.#verdict,
2298
+ compared: this.#compared,
2299
+ mismatched: this.#mismatches,
2300
+ matricesMismatched: this.#matrixMismatches,
2301
+ meshMismatched: this.#meshMismatches,
2302
+ lines: this.#lines,
2303
+ };
2304
+ }
2305
+
2306
+ /**
2307
+ * Read back the dispatch that just ran, once, and resolve only after both targets have settled.
2308
+ *
2309
+ * This is an opt-in diagnostic seam for a harness that must fence one rendered frame before it
2310
+ * advances the fixed-step clock. It does not change the periodic validation path or production
2311
+ * dispatches; a caller that asks twice for one dispatch is refused rather than silently counting
2312
+ * one frame twice.
2313
+ */
2314
+ validateCurrentDispatch(
2315
+ renderer: IRendererLike,
2316
+ frame: number,
2317
+ ): Promise<IWorldGpuFrameValidation> {
2318
+ if (!Number.isInteger(frame) || frame < 0)
2319
+ return Promise.reject(
2320
+ new Error("World GPU frame validation needs a non-negative integer frame."),
2321
+ );
2322
+ if (this.#on === false)
2323
+ return Promise.reject(new Error("World GPU scene validation is unavailable."));
2324
+ if (this.#dispatched <= 0)
2325
+ return Promise.reject(new Error("World GPU frame validation needs a completed dispatch."));
2326
+ if (this.#validating)
2327
+ return Promise.reject(
2328
+ new Error("World GPU frame validation already has a pending readback."),
2329
+ );
2330
+ if (this.#manualDispatch === this.#dispatched)
2331
+ return Promise.reject(new Error("World GPU dispatch was already manually validated."));
2332
+ this.#manualOnly = true;
2333
+ this.#manualDispatch = this.#dispatched;
2334
+ return this.#compare(renderer, frame);
2335
+ }
2336
+
2337
+ /**
2338
+ * Where the independent per-mesh check gets the CPU path's own records, registered once by the
2339
+ * owner and asked only on a check's frame.
2340
+ *
2341
+ * The scene cannot answer this for itself: the records are the owner's, and the meshes whose
2342
+ * indirect offsets are the question are the owner's too. It is asked inside {@link compare}, before
2343
+ * the readback is issued, so the instances it compares are the ones the dispatch just read rather
2344
+ * than whatever the cells hold when the bytes land — the same snapshot rule the rest of the check
2345
+ * is built on, and the reason a walk that streams while a readback is in flight cannot make the
2346
+ * check compare two different worlds.
2347
+ */
2348
+ drawsFrom(provider: () => readonly IMeshDraw[]): void {
2349
+ this.#draws = provider;
2350
+ }
2351
+
2352
+ #draws: (() => readonly IMeshDraw[]) | undefined;
2353
+ #mismatches = 0;
2354
+ #matrixMismatches = 0;
2355
+ #meshMismatches = 0;
2356
+ #compared = 0;
2357
+ #verdict: GpuSceneVerdict = "ok";
2358
+ #lines: string[] = [];
2359
+ #validate = false;
2360
+ #validating = false;
2361
+ /** Manual frame fences replace periodic samples after the first completed fence. */
2362
+ #manualOnly = false;
2363
+ /** The last dispatch a manual frame fence consumed; periodic checks do not move this. */
2364
+ #manualDispatch = -1;
2365
+ /** Reused MAP_READ buffers keep validation from allocating two fresh GPU buffers on every check. */
2366
+ #validationReadbacks: IValidationReadbacks | undefined;
2367
+ /** Whether the owner asked for the GPU-selected main-pass tally; a validation turns it on too. */
2368
+ #tally = false;
2369
+ /** What a launch asked the pyramid occlusion test to do. `measure` never changes what is drawn. */
2370
+ #occlusion: OcclusionMode = "off";
2371
+ /** The max-distance chain, and the previous frame's camera the test reprojects into. */
2372
+ readonly #pyramid = new DepthPyramid();
2373
+ readonly #previousView = new Matrix4();
2374
+ readonly #previousProjection = new Matrix4();
2375
+ #previousDepth:
2376
+ | {
2377
+ texture: DepthTexture;
2378
+ width: number;
2379
+ height: number;
2380
+ samples: number;
2381
+ version: number;
2382
+ }
2383
+ | undefined;
2384
+ readonly #previousEye = new Vector3();
2385
+ readonly #occlusionView = uniform(new Matrix4());
2386
+ readonly #occlusionCut = uniform(1);
2387
+ /** Why the measure mode measured nothing, or `""` while it is measuring. */
2388
+ #occlusionReason = "";
2389
+ /** The last landed tally's occlusion counts, and the running mean over every sample. */
2390
+ #occludedInstances = 0;
2391
+ #occludedTriangles = 0;
2392
+ #occlusionTotalTriangles = 0;
2393
+ #occlusionSample = -1;
2394
+ #occlusionSamples = 0;
2395
+ #occlusionSumInstances = 0;
2396
+ #occlusionSumTriangles = 0;
2397
+ #tallyPending = false;
2398
+ /** Dispatch the in-flight tally readback was issued on, or `-1` when none is in flight. */
2399
+ #tallyRequested = -1;
2400
+ /** Dispatch whose GPU state the landed tally bytes hold, or `-1` before the first lands. */
2401
+ #tallySample = -1;
2402
+ #tallyInstances = 0;
2403
+ #tallyTriangles = 0;
2404
+ #watched = false;
2405
+ /**
2406
+ * The main meshes the owner has dressed against these buffers, and the main meshes it holds. It is
2407
+ * the owner's, not this class's: a scene that reports itself on over a ring it never dressed was
2408
+ * invisible from here, and `dressed=0/21094` is what a real run printed. See {@link announce}.
2409
+ */
2410
+ #census = { dressed: 0, meshes: 0 };
2411
+ /** The device's last uncaptured error, reported by the next check and then cleared. */
2412
+ #deviceError = "";
2413
+
2414
+ /**
2415
+ * Ask for the indirect args back, once, and tally what the GPU selected into them.
2416
+ *
2417
+ * This is the certificate the frame budget could not have: `renderer.info.render.triangles` counts
2418
+ * a mesh's CPU window, which for an indirect draw is its capacity and therefore an upper bound,
2419
+ * while the args record holds the instance count the kernel actually wrote. The readback is the
2420
+ * same one a validation uses — the renderer's one staging buffer — on a slower clock, and a frame
2421
+ * whose predecessor is still in flight is skipped rather than queued.
2422
+ */
2423
+ #tallyRead(renderer: IRendererLike): void {
2424
+ const args = this.#buffers?.args;
2425
+ if (args === undefined) return;
2426
+ const issued = this.#dispatched;
2427
+ this.#tallyRequested = issued;
2428
+ this.#tallyPending = true;
2429
+ // Streaming may grow the args tail while this copy is in flight. Decode its own layout.
2430
+ const regions = this.#regions.map((region) => ({ argsIndex: region.argsIndex }));
2431
+ const occlusionReason = this.#occlusionReason;
2432
+ renderer
2433
+ .readback(args)
2434
+ .then((bytes) => this.#landTally(bytes, issued, regions, occlusionReason))
2435
+ .catch(() => {
2436
+ this.#tallyPending = false;
2437
+ });
2438
+ }
2439
+
2440
+ /**
2441
+ * Sum the landed args records: `instanceCount` over every record, and `instanceCount x indexCount`
2442
+ * divided by three. A record the GPU never wrote reads as the zero it holds, which is correct —
2443
+ * a key that selected nothing draws nothing.
2444
+ */
2445
+ #landTally(
2446
+ bytes: ArrayBuffer,
2447
+ issued: number,
2448
+ regions: readonly Pick<IRegion, "argsIndex">[],
2449
+ occlusionReason: string,
2450
+ ): void {
2451
+ this.#tallyPending = false;
2452
+ const words = new Uint32Array(bytes);
2453
+ let instances = 0;
2454
+ let products = 0;
2455
+ for (const region of regions) {
2456
+ const record = region.argsIndex * DRAW_ARGS_WORDS;
2457
+ const count = word(words, record + 1);
2458
+ instances += count;
2459
+ products += count * word(words, record);
2460
+ }
2461
+ this.#tallyInstances = instances;
2462
+ this.#tallyTriangles = products / 3;
2463
+ this.#tallySample = issued;
2464
+ if (this.#occlusion !== "off") this.#landOcclusion(words, issued, regions, occlusionReason);
2465
+ }
2466
+
2467
+ /**
2468
+ * What the measured cull hid, out of the same landed bytes as the drawn counts.
2469
+ *
2470
+ * The tail of the args buffer is one word per key of measured-occlusion instances, so a hidden
2471
+ * part's triangles are that word times its own `indexCount` — the same product the tally above
2472
+ * sums over the records, which is why both numbers can be divided into a share without a second
2473
+ * readback or a second clock.
2474
+ */
2475
+ #landOcclusion(
2476
+ words: Uint32Array,
2477
+ issued: number,
2478
+ regions: readonly Pick<IRegion, "argsIndex">[],
2479
+ sampleReason: string,
2480
+ ): void {
2481
+ let reason = sampleReason;
2482
+ const tail = regions.length * DRAW_ARGS_WORDS;
2483
+ if (reason === "" && words.length < tail + regions.length) reason = "skipped: short readback";
2484
+ if (
2485
+ reason === "" &&
2486
+ regions.some(
2487
+ (region, index) =>
2488
+ word(words, tail + index) > word(words, region.argsIndex * DRAW_ARGS_WORDS + 1),
2489
+ )
2490
+ )
2491
+ reason = "skipped: inconsistent readback";
2492
+ if (reason !== "") {
2493
+ this.#occlusionReason = reason;
2494
+ console.info(
2495
+ `TN_WORLD_GPU_SCENE_OCCLUSION mode=${this.#occlusion} dispatch=${String(issued)} skipped=1 reason=${reason}`,
2496
+ );
2497
+ return;
2498
+ }
2499
+ let instances = 0;
2500
+ let products = 0;
2501
+ for (const [index, region] of regions.entries()) {
2502
+ const count = word(words, regions.length * DRAW_ARGS_WORDS + index);
2503
+ instances += count;
2504
+ products += count * word(words, region.argsIndex * DRAW_ARGS_WORDS);
2505
+ }
2506
+ this.#occludedInstances = instances;
2507
+ this.#occludedTriangles = products / 3;
2508
+ this.#occlusionReason = "";
2509
+ this.#occlusionSample = issued;
2510
+ this.#occlusionTotalTriangles = this.#tallyTriangles;
2511
+ this.#occlusionSamples += 1;
2512
+ this.#occlusionSumInstances += instances;
2513
+ this.#occlusionSumTriangles += this.#occludedTriangles;
2514
+ const report = this.report().occlusion;
2515
+ if (report === undefined) return;
2516
+ const line =
2517
+ `TN_WORLD_GPU_SCENE_OCCLUSION mode=${report.mode} levels=${String(report.levels)} ` +
2518
+ `dispatch=${String(issued)} reason=${report.reason || "none"} ` +
2519
+ `wouldCullInstances=${String(report.instances)} wouldCullTriangles=${String(report.triangles)} ` +
2520
+ `gpuInstances=${String(this.#tallyInstances)} gpuTriangles=${String(this.#tallyTriangles)} ` +
2521
+ `share=${report.share.toFixed(4)}`;
2522
+ console.info(line);
2523
+ }
2524
+
2525
+ /**
2526
+ * Read the indirect args and the compacted matrices back and hold both against the reference, over
2527
+ * the placements, camera and gate table the dispatch just read — copied at this moment, in this
2528
+ * turn, so a structural change landing while the bytes are in flight changes nothing about what
2529
+ * they are held against.
2530
+ *
2531
+ * The reference is {@link cullAndSelect} on the CPU, so this is the kernel measured against the
2532
+ * loop it mirrors — the only place the TSL itself is ever checked. It costs two queue submissions
2533
+ * and two mapped buffers every {@link VALIDATE_EVERY} dispatches, which is why it is a mode and
2534
+ * not a default: a game never pays for it and a walk is never measured with it on. One check is in
2535
+ * flight at a time, so every report answers a dispatch of its own.
2536
+ *
2537
+ * The counts alone are not the draw: a key can land every instance it owes into a record whose
2538
+ * `firstInstance` points at the wrong run, or whose `indexCount` names no triangle, or into a
2539
+ * region the mesh does not read — and a real WebGPU walk printed `ok` over 200 keys whose
2540
+ * `indexCount` was zero, with the forest it was supposed to draw missing from the picture and its
2541
+ * shadows still on the ground. So the matrices are read back too, and the same check that reads
2542
+ * them holds the record's two CPU-owned words against what the key's geometry and layout say.
2543
+ *
2544
+ * And the third check reads nothing this file wrote: the owner's own dressed meshes, each with the
2545
+ * indirect record its own geometry points at, against the instances the owner's own CPU path
2546
+ * composes for the key that mesh is named. Both families above can only confirm that the kernel
2547
+ * and the reference agree, which a wrong key-to-record mapping makes them agree on; only these two
2548
+ * were not written by the same hand. See {@link compareMeshDraws}.
2549
+ */
2550
+ #compare(renderer: IRendererLike, frame = -1): Promise<IWorldGpuFrameValidation> {
2551
+ const snapshot = this.#snapshot();
2552
+ if (snapshot.args === undefined || snapshot.drawn === undefined)
2553
+ return Promise.reject(new Error("World GPU frame validation has no dispatched buffers."));
2554
+ const reference = cullAndSelect(snapshot);
2555
+ // Taken now, with the snapshot, and not when the readback lands: see `drawsFrom`.
2556
+ const draws = this.#draws?.() ?? [];
2557
+ const issued = this.#dispatched;
2558
+ const readbacks = this.#readbacksFor(snapshot);
2559
+ this.#validating = true;
2560
+ const occlusionReason = this.#occlusionReason;
2561
+ const reads = [
2562
+ renderer.readback(snapshot.args, readbacks.args),
2563
+ renderer.readback(snapshot.drawn, readbacks.drawn),
2564
+ ] as const;
2565
+ const complete = Promise.all(reads)
2566
+ .then(([argsBytes, drawnBytes]) => {
2567
+ // The same landed args feed the tally, so a validation pays for it and this adds no copy.
2568
+ this.#landTally(argsBytes, issued, snapshot.regions, occlusionReason);
2569
+ const input = this.#against(
2570
+ snapshot,
2571
+ reference,
2572
+ new Uint32Array(argsBytes),
2573
+ new Float32Array(drawnBytes),
2574
+ draws,
2575
+ );
2576
+ const report = this.#publish(renderer, input);
2577
+ return { ...input, dispatch: issued, frame, verdict: report.verdict };
2578
+ })
2579
+ .catch((reason: unknown) => {
2580
+ // A readback that never lands is a check that never ran, and saying so is the whole point:
2581
+ // this line used to end the chain and leave the last verdict standing as if it were fresh.
2582
+ const input: IGpuSceneComparison = {
2583
+ cause: `readback-failed: ${String(reason instanceof Error ? reason.message : reason)}`,
2584
+ compared: 0,
2585
+ deviceError: this.#deviceError,
2586
+ instancesCpu: 0,
2587
+ instancesGpu: 0,
2588
+ matricesMismatched: 0,
2589
+ meshMismatched: 0,
2590
+ meshMismatches: [],
2591
+ mismatched: 0,
2592
+ mismatches: [],
2593
+ matrixMismatches: [],
2594
+ placed: snapshot.placed,
2595
+ };
2596
+ const report = this.#publish(renderer, input);
2597
+ return { ...input, dispatch: issued, frame, verdict: report.verdict };
2598
+ });
2599
+ // Promise.all reports the first failure, but its rejection does not mean the other GPU copy has
2600
+ // stopped. Release only after both copies settle, so a pending map cannot race a reused target.
2601
+ return complete.finally(async () => {
2602
+ await Promise.allSettled(reads);
2603
+ readbacks.args.release();
2604
+ readbacks.drawn.release();
2605
+ if (this.#validationReadbacks !== readbacks) {
2606
+ readbacks.args.dispose();
2607
+ readbacks.drawn.dispose();
2608
+ }
2609
+ this.#validating = false;
2610
+ });
2611
+ }
2612
+
2613
+ #readbacksFor(snapshot: IValidationSnapshot): IValidationReadbacks {
2614
+ const argsBytes = Math.max(
2615
+ 4,
2616
+ (snapshot.args as { array: { byteLength: number } }).array.byteLength,
2617
+ );
2618
+ const drawnBytes = Math.max(
2619
+ 4,
2620
+ (snapshot.drawn as { array: { byteLength: number } }).array.byteLength,
2621
+ );
2622
+ const current = this.#validationReadbacks;
2623
+ if (
2624
+ current !== undefined &&
2625
+ current.args.maxByteLength >= argsBytes &&
2626
+ current.drawn.maxByteLength >= drawnBytes
2627
+ )
2628
+ return current;
2629
+ current?.args.dispose();
2630
+ current?.drawn.dispose();
2631
+ this.#validationReadbacks = {
2632
+ args: new ReadbackBuffer(argsBytes),
2633
+ drawn: new ReadbackBuffer(drawnBytes),
2634
+ };
2635
+ return this.#validationReadbacks;
2636
+ }
2637
+
2638
+ /**
2639
+ * A copy of everything the dispatch that is running right now reads: the source records, the slot
2640
+ * and gate tables, the region and args layout, the frustum planes and the eye.
2641
+ *
2642
+ * One flat array holds the placement records and each copy is a view into it, so a twenty-thousand
2643
+ * placement walk costs one allocation rather than forty thousand. The gate and region tables are
2644
+ * copied shallowly, which is whole: an asset's gate definition is replaced rather than edited, and
2645
+ * a region is spread into a fresh object, so nothing reachable from a snapshot can move under it.
2646
+ */
2647
+ #snapshot(): IValidationSnapshot {
2648
+ const flat = new Float32Array(this.placements.length * PLACEMENT_WORDS);
2649
+ const placements = this.placements.map((placement, index) => {
2650
+ const at = index * PLACEMENT_WORDS;
2651
+ flat.set(placement.matrix, at);
2652
+ flat.set(placement.centre, at + LOCAL_WORDS);
2653
+ return {
2654
+ centre: flat.subarray(at + LOCAL_WORDS, at + LOCAL_WORDS + 4),
2655
+ matrix: flat.subarray(at, at + LOCAL_WORDS),
2656
+ scale: placement.scale,
2657
+ slot: placement.slot,
2658
+ };
2659
+ });
2660
+ return {
2661
+ args: this.#buffers?.args,
2662
+ camera: {
2663
+ planes: this.#planes.slice(),
2664
+ x: this.#eye.value.x,
2665
+ y: this.#eye.value.y,
2666
+ z: this.#eye.value.z,
2667
+ },
2668
+ count: placements.length,
2669
+ drawn: this.#buffers?.drawn,
2670
+ placed: this.#live,
2671
+ placements,
2672
+ regionCount: this.#regions.length,
2673
+ regions: this.#regions.map((region) => ({ ...region, local: region.local.slice() })),
2674
+ slots: this.gates().map((slot) => ({ ...slot })),
2675
+ };
2676
+ }
2677
+
2678
+ /** One readback's bytes against its own dispatch's reference: the counts, then the draw, then the meshes. */
2679
+ #against(
2680
+ snapshot: IValidationSnapshot,
2681
+ reference: IKernelResult,
2682
+ gpu: Uint32Array,
2683
+ drawn: Float32Array,
2684
+ draws: readonly IMeshDraw[],
2685
+ ): IGpuSceneComparison {
2686
+ const mismatches: string[] = [];
2687
+ const matrixMismatches: string[] = [];
2688
+ let mismatched = 0;
2689
+ let matricesMismatched = 0;
2690
+ let instancesGpu = 0;
2691
+ let instancesCpu = 0;
2692
+ for (const [index, region] of snapshot.regions.entries()) {
2693
+ const record = region.argsIndex * DRAW_ARGS_WORDS;
2694
+ // A readback that landed short is a mismatch, not a hole in the report: `word` reads out of
2695
+ // range as the zero a record that was never written holds.
2696
+ const landed = word(gpu, record + 1);
2697
+ const expected = reference.counts[index] as number;
2698
+ instancesGpu += landed;
2699
+ instancesCpu += expected;
2700
+ if (landed !== expected) {
2701
+ mismatched += 1;
2702
+ if (mismatches.length < VALIDATE_REPORTED_KEYS)
2703
+ mismatches.push(
2704
+ `${region.name ?? `#${String(index)}`} gpu=${String(landed)} cpu=${String(expected)}`,
2705
+ );
2706
+ }
2707
+ const firstInstance = word(gpu, record + 4);
2708
+ const indexCount = word(gpu, record);
2709
+ const agrees =
2710
+ firstInstance === region.start &&
2711
+ indexCount === region.indexCount &&
2712
+ sameMatrices(
2713
+ drawn,
2714
+ firstInstance,
2715
+ landed,
2716
+ reference.drawn,
2717
+ region.start,
2718
+ expected,
2719
+ MATRIX_TOLERANCE,
2720
+ );
2721
+ if (agrees) continue;
2722
+ matricesMismatched += 1;
2723
+ if (matrixMismatches.length < MATRIX_REPORTED_KEYS)
2724
+ matrixMismatches.push(
2725
+ `${region.name ?? `#${String(index)}`} ` +
2726
+ `first gpu=${xyz(drawn, firstInstance)} cpu=${xyz(reference.drawn, region.start)} ` +
2727
+ `firstInstance gpu=${String(firstInstance)} expected=${String(region.start)} ` +
2728
+ `indexCount gpu=${String(indexCount)} expected=${String(region.indexCount)}`,
2729
+ );
2730
+ }
2731
+ // Off the snapshot's own regions: which key each mesh is, which record it reads and what it
2732
+ // should be holding are the owner's numbers, and the whole point is that nothing in this file
2733
+ // chose them.
2734
+ const meshes = compareMeshDraws(gpu, drawn, draws, snapshot.regions);
2735
+ // Both totals at zero is the case that never says why it saw nothing: name the snapshot's own
2736
+ // camera and nearest live placement, the two inputs a real static validation needs to tell a
2737
+ // missing source from a camera, sphere, range or frustum that rejected every one it held.
2738
+ const probe =
2739
+ instancesGpu === 0 && instancesCpu === 0 ? zeroComparisonProbe(snapshot) : undefined;
2740
+ return {
2741
+ compared: snapshot.regions.length,
2742
+ deviceError: this.#deviceError,
2743
+ instancesCpu,
2744
+ instancesGpu,
2745
+ matricesMismatched,
2746
+ meshMismatched: meshes.mismatched,
2747
+ meshMismatches: meshes.mismatches,
2748
+ mismatched,
2749
+ mismatches,
2750
+ matrixMismatches,
2751
+ placed: snapshot.placed,
2752
+ ...(probe === undefined ? {} : { probe }),
2753
+ };
2754
+ }
2755
+
2756
+ /**
2757
+ * One verdict, stored for a harness to read and printed once, with its cause if it failed.
2758
+ *
2759
+ * The line also carries what the device and this scene held when the check reported, read here
2760
+ * rather than polled: `renderer.raw.info.memory` is Three's own tally and `footprint()` is this
2761
+ * scene's allocation, so a readback that leaks its staging buffer shows up as growing
2762
+ * `readbackBuffers`/`readbackBuffersSize` across reports instead of only as a later OOM. A backend
2763
+ * that tracks no memory field contributes none, and no field is ever printed as a fake zero.
2764
+ */
2765
+ #publish(renderer: IRendererLike, input: IGpuSceneComparison): IGpuSceneValidation {
2766
+ const source = (renderer.raw as { info?: { memory?: Partial<Record<string, unknown>> } })?.info
2767
+ ?.memory;
2768
+ let memory: GpuSceneMemory | undefined;
2769
+ // A backend Three keeps no memory tally for contributes nothing, footprint included: a scene
2770
+ // number printed next to absent device numbers reads as if the device had been measured.
2771
+ if (source !== undefined) {
2772
+ memory = {};
2773
+ for (const name of MEMORY_FIELDS) {
2774
+ const value = source[name];
2775
+ if (typeof value === "number" && Number.isFinite(value)) memory[name] = value;
2776
+ }
2777
+ const footprint = Object.values(this.footprint());
2778
+ if (footprint.length > 0)
2779
+ memory.footprintBytes = footprint.reduce((sum, buffer) => sum + buffer.bytes, 0);
2780
+ }
2781
+ const report = validationReport(
2782
+ Object.keys(memory ?? {}).length === 0 ? input : { ...input, memory },
2783
+ );
2784
+ this.#verdict = report.verdict;
2785
+ this.#compared = input.compared;
2786
+ this.#mismatches = input.mismatched;
2787
+ this.#matrixMismatches = input.matricesMismatched;
2788
+ this.#meshMismatches = input.meshMismatched;
2789
+ this.#lines = [...report.lines];
2790
+ // Reported, so cleared: an error is folded into exactly the check that saw it.
2791
+ this.#deviceError = "";
2792
+ const name =
2793
+ "log" in renderer ? (renderer.log as ((message: string) => void) | undefined) : undefined;
2794
+ const say = typeof name === "function" ? name : console.info.bind(console);
2795
+ say(report.line);
2796
+ for (const line of report.lines) say(`TN_WORLD_GPU_SCENE_VALIDATE ${line}`);
2797
+ return report;
2798
+ }
2799
+
2800
+ dispose(): void {
2801
+ const readbacks = this.#validationReadbacks;
2802
+ this.#validationReadbacks = undefined;
2803
+ if (!this.#validating) {
2804
+ readbacks?.args.dispose();
2805
+ readbacks?.drawn.dispose();
2806
+ }
2807
+ this.#kernel = undefined;
2808
+ this.#shadowKernel = undefined;
2809
+ this.#shadow = undefined;
2810
+ this.#shadowProvider = undefined;
2811
+ this.#buffers = undefined;
2812
+ this.placements.length = 0;
2813
+ this.#regions.length = 0;
2814
+ this.#keysByName.clear();
2815
+ this.#slotsByAsset.clear();
2816
+ this.#groups.clear();
2817
+ this.#order.length = 0;
2818
+ this.#free.length = 0;
2819
+ this.#live = 0;
2820
+ this.#on = false;
2821
+ this.#tallyPending = false;
2822
+ this.#tallyRequested = -1;
2823
+ this.#tallySample = -1;
2824
+ this.#pyramid.dispose();
2825
+ }
2826
+
2827
+ readonly #planeVectors = Array.from({ length: 6 }, () => new Vector4());
2828
+ #eye = uniform(new Vector3());
2829
+ #counts = uniform(new Vector4());
2830
+ /**
2831
+ * The adaptive LOD bias the kernel scales camera distance by before the gate compare. Set from
2832
+ * `WorldCells`' control loop through {@link setLodBias}; 1 is exactly as authored.
2833
+ */
2834
+ #lodBias = uniform(1);
2835
+ #planeUniforms = this.#planeVectors.map((plane) => uniform(plane));
2836
+ /**
2837
+ * The shadow kernel's own three, kept apart from the camera's: a level's planes are written here
2838
+ * and the main pass's own are never disturbed, so the two dispatches in one frame cannot read each
2839
+ * other's uniforms. Its gate and base are the level's own texel gate and chain level; its eye and
2840
+ * LOD bias are the main pass's, which this frame's main dispatch already set.
2841
+ */
2842
+ #shadowPlaneVectors = Array.from({ length: 6 }, () => new Vector4());
2843
+ #shadowGate = uniform(0);
2844
+ #shadowBase = uniform(0);
2845
+ #shadowPlaneUniforms = this.#shadowPlaneVectors.map((plane) => uniform(plane));
2846
+
2847
+ #ensure(): IGpuSceneBuffers | undefined {
2848
+ if (this.#buffers !== undefined) return this.#buffers;
2849
+ this.#buffers = {
2850
+ args: storageAttribute(IndirectStorageBufferAttribute, "uint", DRAW_ARGS_WORDS, Uint32Array),
2851
+ // One whole `mat4` per instance, which is also what a dressed batch's `instanceMatrix` has to
2852
+ // be: this attribute is four words per instance, the kernel bound it as a `mat4`, and a
2853
+ // one-instance buffer of it was 16 bytes against a 64-byte minimum, so the device refused
2854
+ // every dispatch and the kernel never ran. See `storageAttribute`.
2855
+ drawn: storageAttribute(StorageInstancedBufferAttribute, "mat4", 1),
2856
+ gates: storageAttribute(StorageBufferAttribute, "vec4", 1),
2857
+ keys: storageAttribute(StorageBufferAttribute, "vec4", 1),
2858
+ levels: storageAttribute(StorageBufferAttribute, "vec4", 1),
2859
+ locals: storageAttribute(StorageBufferAttribute, "mat4", 1),
2860
+ source: storageAttribute(StorageBufferAttribute, "GpuPlacement", SOURCE_FLOOR),
2861
+ };
2862
+ this.#version += 1;
2863
+ return this.#buffers;
2864
+ }
2865
+
2866
+ /**
2867
+ * Grow one of the scene's own storage buffers by doubling, or leave it when it already has room.
2868
+ *
2869
+ * `needed` is a count of elements of the type the kernel declares that buffer as, never a word
2870
+ * count and never a stride: the element size comes from {@link storageAttribute} and the count is
2871
+ * the only thing a caller may choose. Each of these is read by a built kernel or named by a
2872
+ * geometry's `setIndirect`, so a swap is structural — the kernel is a new pipeline and the main
2873
+ * meshes are re-dressed against the new attribute. That is why the buffers start at one and
2874
+ * double: a key or a placement arriving is the event, and a frame never reallocates.
2875
+ */
2876
+ #growOf(name: BufferName, needed: number): boolean {
2877
+ const buffers = this.#buffers;
2878
+ if (buffers === undefined) return false;
2879
+ const current = buffers[name] as BufferAttribute;
2880
+ // The allocation `#ensure` made, at the new count, so a regrow cannot land a different class or
2881
+ // a different element size than the pipeline the kernel was built against.
2882
+ const grown = growBuffer(current, needed, (capacity) =>
2883
+ name === "args"
2884
+ ? storageAttribute(IndirectStorageBufferAttribute, "uint", capacity, Uint32Array)
2885
+ : name === "drawn"
2886
+ ? storageAttribute(StorageInstancedBufferAttribute, "mat4", capacity)
2887
+ : storageAttribute(StorageBufferAttribute, STORAGE_PLAIN[name], capacity),
2888
+ );
2889
+ if (grown === current) return true;
2890
+ this.#buffers = { ...buffers, [name]: grown };
2891
+ // The attributes the kernel is built from changed, so the kernel is a new pipeline: a structural
2892
+ // event, and the only one this class pays a compile for. The shadow kernel reads the same
2893
+ // placements, keys, locals, gates and levels, so it is rebuilt with it.
2894
+ this.#kernel = undefined;
2895
+ this.#shadowKernel = undefined;
2896
+ this.#version += 1;
2897
+ return true;
2898
+ }
2899
+
2900
+ #growDrawn(): void {
2901
+ this.#growOf("drawn", this.#drawnCapacity);
2902
+ }
2903
+
2904
+ #reserve(count: number): boolean {
2905
+ // A ring-sized floor, so the first few placements do not each pay a reallocation.
2906
+ return this.#growOf("source", Math.max(SOURCE_FLOOR, count));
2907
+ }
2908
+
2909
+ #writePlacement(index: number): void {
2910
+ const buffers = this.#buffers;
2911
+ const placement = this.placements[index];
2912
+ if (buffers === undefined || placement === undefined) return;
2913
+ const at = index * PLACEMENT_WORDS;
2914
+ const array = buffers.source.array as Float32Array;
2915
+ array.set(placement.matrix, at);
2916
+ array[at + 16] = placement.centre[0] as number;
2917
+ array[at + 17] = placement.centre[1] as number;
2918
+ array[at + 18] = placement.centre[2] as number;
2919
+ array[at + 19] = placement.centre[3] as number;
2920
+ array[at + 20] = placement.slot;
2921
+ // `info.y` is the placement's uniform scale, read by the kernel's impostor gate. The remaining
2922
+ // `info` words stay whatever they were, which is zero.
2923
+ array[at + 21] = placement.scale ?? 1;
2924
+ addRange(buffers.source, at, PLACEMENT_WORDS);
2925
+ buffers.source.needsUpdate = true;
2926
+ }
2927
+
2928
+ #writeKey(index: number): void {
2929
+ // Read the live set, not the one the caller held: growing a buffer replaces the attribute, and
2930
+ // the record being written is the one the draw and the kernel will read.
2931
+ const buffers = this.#buffers;
2932
+ const region = this.#regions[index];
2933
+ if (buffers === undefined || region === undefined) return;
2934
+ const at = index * VEC4_WORDS;
2935
+ const keys = buffers.keys.array as Float32Array;
2936
+ keys[at] = region.start;
2937
+ keys[at + 1] = region.capacity;
2938
+ keys[at + 2] = region.argsIndex;
2939
+ addRange(buffers.keys, at, VEC4_WORDS);
2940
+ buffers.keys.needsUpdate = true;
2941
+ (buffers.locals.array as Float32Array).set(region.local, index * LOCAL_WORDS);
2942
+ addRange(buffers.locals, index * LOCAL_WORDS, LOCAL_WORDS);
2943
+ buffers.locals.needsUpdate = true;
2944
+ const args = buffers.args.array as Uint32Array;
2945
+ const record = region.argsIndex * DRAW_ARGS_WORDS;
2946
+ args[record] = region.indexCount;
2947
+ args[record + 1] = 0;
2948
+ args[record + 2] = 0;
2949
+ args[record + 3] = 0;
2950
+ args[record + 4] = region.start;
2951
+ buffers.args.needsUpdate = true;
2952
+ this.#writeShadowKey(index);
2953
+ }
2954
+
2955
+ /**
2956
+ * Write the whole gate table, which only changes when an asset's levels are adopted.
2957
+ *
2958
+ * Sized before it is written, not after: the table holds one `vec4` per asset and per level, and
2959
+ * a write past the end of a `Float32Array` is a silent no-op. Growing afterwards and copying the
2960
+ * short array over the long one kept the first element and dropped the rest, which is a gate table
2961
+ * that reads as every asset having no levels and no cull distance.
2962
+ */
2963
+ #writeSlots(): void {
2964
+ if (this.#buffers === undefined) return;
2965
+ let levels = 0;
2966
+ for (const asset of this.#order)
2967
+ levels += (this.#slotsByAsset.get(asset) as IAssetSlot).levels.length;
2968
+ this.#growOf("gates", Math.max(1, this.#order.length));
2969
+ this.#growOf("levels", Math.max(1, levels));
2970
+ const live = this.#buffers;
2971
+ if (live === undefined) return;
2972
+ const gates = live.gates.array as Float32Array;
2973
+ const levelTable = live.levels.array as Float32Array;
2974
+ let level = 0;
2975
+ for (const [slot, asset] of this.#order.entries()) {
2976
+ const definition = this.#slotsByAsset.get(asset) as IAssetSlot;
2977
+ const first = level;
2978
+ for (const [index, gate] of definition.levels.entries()) {
2979
+ const at = level * VEC4_WORDS;
2980
+ levelTable[at] = definition.distances[index] ?? 0;
2981
+ levelTable[at + 1] = gate.firstKey;
2982
+ levelTable[at + 2] = gate.parts;
2983
+ // `w` marks the whole-asset impostor's terminal gate: its stored distance is the base-sphere
2984
+ // projected one, and the kernel multiplies it by the placement's own scale. See `levelAtGates`.
2985
+ levelTable[at + 3] =
2986
+ definition.impostor === true && index === definition.levels.length - 1 ? 1 : 0;
2987
+ level += 1;
2988
+ }
2989
+ const at = slot * VEC4_WORDS;
2990
+ gates[at] = first;
2991
+ gates[at + 1] = definition.levels.length;
2992
+ gates[at + 2] = definition.cull ?? 0;
2993
+ // Bit 0: authored cull distance; bit 1: authored LODs must not fall back to a casting shape.
2994
+ gates[at + 3] =
2995
+ (definition.cull === undefined ? 0 : 1) + (definition.shadowFallback === false ? 2 : 0);
2996
+ }
2997
+ live.gates.needsUpdate = true;
2998
+ live.levels.needsUpdate = true;
2999
+ }
3000
+
3001
+ /**
3002
+ * The two dispatches, mirroring {@link cullAndSelect} branch for branch: one thread per key
3003
+ * zeroes that key's instance count, one thread per resident placement appends its matrix to each
3004
+ * of its level's parts.
3005
+ */
3006
+ #buildKernel(): { readonly cull: unknown; readonly clear: unknown } | undefined {
3007
+ const buffers = this.#buffers;
3008
+ if (buffers === undefined) return undefined;
3009
+ const source = nodes(storage(buffers.source, PlacementStruct, buffers.source.count));
3010
+ const drawn = nodes(storage(buffers.drawn, "mat4", buffers.drawn.count));
3011
+ const argsPlain = nodes(storage(buffers.args, "uint", buffers.args.count));
3012
+ const argsAtomic = nodes(storage(buffers.args, "uint", buffers.args.count).toAtomic());
3013
+ const keys = nodes(storage(buffers.keys, "vec4", buffers.keys.count));
3014
+ const locals = nodes(storage(buffers.locals, "mat4", buffers.locals.count));
3015
+ const gates = nodes(storage(buffers.gates, "vec4", buffers.gates.count));
3016
+ const levels = nodes(storage(buffers.levels, "vec4", buffers.levels.count));
3017
+ const counts = nodes(this.#counts);
3018
+ const eye = nodes(this.#eye);
3019
+ const bias = nodes(this.#lodBias);
3020
+ const planes = this.#planeUniforms.map((plane) => nodes(plane));
3021
+ // Measuring doubles the clear: the second thread per key zeroes that key's word of the
3022
+ // measured-occlusion tally, which is why the args buffer is sized for it (see `argsWords`).
3023
+ // A run that is not measuring never pays the second thread.
3024
+ const clearWidth = this.#occlusion === "off" ? 1 : 2;
3025
+ const clear = Fn(() => {
3026
+ If(instanceIndex.greaterThanEqual(counts.w.mul(clearWidth)), () => Return());
3027
+ If(instanceIndex.lessThan(counts.w), () => {
3028
+ const key = keys.element(instanceIndex);
3029
+ argsPlain.element(key.z.mul(DRAW_ARGS_WORDS).add(1)).assign(int(0));
3030
+ });
3031
+ If(instanceIndex.greaterThanEqual(counts.w), () => {
3032
+ argsPlain
3033
+ .element(
3034
+ nodes(counts.w.mul(DRAW_ARGS_WORDS)).add(
3035
+ nodes(float(instanceIndex).sub(counts.w).floor()),
3036
+ ),
3037
+ )
3038
+ .assign(int(0));
3039
+ });
3040
+ })().compute(Math.max(1, buffers.keys.count * clearWidth));
3041
+ const cull = Fn(() => {
3042
+ If(instanceIndex.greaterThanEqual(counts.x), () => Return());
3043
+ const placement = source.element(instanceIndex);
3044
+ const centre = placement.get("centre");
3045
+ const matrix = placement.get("matrix");
3046
+ const slot = placement.get("info").x;
3047
+ If(slot.lessThan(0.0), () => Return());
3048
+ If(slot.greaterThanEqual(counts.y), () => Return());
3049
+ const radius = centre.w;
3050
+ for (const plane of planes)
3051
+ If(plane.dot(centre.xyz).lessThan(radius.negate()), () => Return());
3052
+ const gate = gates.element(slot);
3053
+ const distance = length(vec3(centre.x.sub(eye.x), 0.0, centre.z.sub(eye.z)));
3054
+ If(gate.w.mod(2.0).greaterThan(0.5).and(distance.greaterThan(gate.z)), () => Return());
3055
+ // Cull above is the authored distance; the level below is the same distance scaled by the
3056
+ // adaptive bias, mirroring `cullAndSelect` and the CPU `model-lod` path.
3057
+ const lodDistance = nodes(distance).mul(bias as never);
3058
+ // The level, by the same ascending test the CPU runs: the last gate the placement is past.
3059
+ // The loop is bounded by `gate.y` rather than unrolled, because a baked chain can carry more
3060
+ // levels than any fixed count, and a level the loop stopped short of is a placement drawn at
3061
+ // the wrong shape by however many levels it missed.
3062
+ const level = int(0).toVar();
3063
+ // The placement's own uniform scale, written into `info.y`; the whole-asset impostor's terminal
3064
+ // gate is the base projected distance and is scaled by it. A mirrored placement's scale is
3065
+ // negative, and the extent it reaches is the same, so the kernel takes the magnitude exactly as
3066
+ // `levelAtGates` does; `info.y` is already finite-sanitised when the record is written.
3067
+ const scale = abs(placement.get("info").y);
3068
+ Loop({ start: int(1), end: gate.y, type: "int", condition: "<" }, ({ i }: { i: unknown }) => {
3069
+ const candidate = levels.element(gate.x.add(i as never));
3070
+ const threshold = nodes(candidate.x).toVar();
3071
+ // Only the terminal level carries this mark: its stored distance is the base-sphere projected
3072
+ // one, so its real threshold is `max(strictly after last source gate, base * |scale|)`. The
3073
+ // source floor is the previous level's own authored gate, unscaled and nudged one f32 step,
3074
+ // so a small scale cannot starve the last source level by sharing its switch distance.
3075
+ If(candidate.w.greaterThan(0.5), () => {
3076
+ const previous = levels.element(gate.x.add(i as never).sub(1)).x;
3077
+ const floor = previous.add(abs(previous).mul(GATE_STEP));
3078
+ threshold.assign(max(floor, candidate.x.mul(scale)));
3079
+ });
3080
+ // A level the prewarm has minted no key for is not taken: the gate table names every level of
3081
+ // an asset from the moment it is adopted, and the draw loop below would run this level's
3082
+ // zero keys, so the placement would be selected and drawn nowhere while the CPU path drew it
3083
+ // and its shadow halves drew under it. The last level that has keys keeps it. See
3084
+ // `drawableLevel`, which the reference mirrors.
3085
+ If(lodDistance.greaterThan(threshold), () => {
3086
+ If(candidate.z.greaterThan(0.5), () => {
3087
+ level.assign(i as never);
3088
+ });
3089
+ });
3090
+ });
3091
+ const at = levels.element(gate.x.add(level));
3092
+ // The pyramid test, once per placement: a placement the frustum and the gates kept, reprojected
3093
+ // into the previous frame's pyramid. Measured only, so the write below happens either way and
3094
+ // the indirect counts are develop's.
3095
+ const hidden = float(0).toVar();
3096
+ if (this.#occlusion !== "off" && this.#pyramid.levels > 0)
3097
+ hidden.assign(
3098
+ this.#pyramid.occluded(centre.xyz, radius, this.#occlusionView, this.#occlusionCut),
3099
+ );
3100
+ Loop({ start: int(0), end: at.z, type: "int", condition: "<" }, ({ i }: { i: unknown }) => {
3101
+ const keyIndex = at.y.add(i as never);
3102
+ const key = keys.element(keyIndex);
3103
+ If(hidden.greaterThan(0.5), () => {
3104
+ atomicAdd(argsAtomic.element(counts.w.mul(DRAW_ARGS_WORDS).add(keyIndex)), int(1));
3105
+ });
3106
+ const taken = nodes(
3107
+ atomicAdd(argsAtomic.element(key.z.mul(DRAW_ARGS_WORDS).add(1)), int(1)),
3108
+ );
3109
+ If(taken.toFloat().lessThan(key.y), () => {
3110
+ drawn.element(key.x.add(taken)).assign(matrix.mul(locals.element(keyIndex)));
3111
+ });
3112
+ });
3113
+ })().compute(Math.max(1, buffers.source.count));
3114
+ clear.setName("worldGpuSceneClear");
3115
+ cull.setName("worldGpuSceneCull");
3116
+ this.#kernel = { clear, cull };
3117
+ return this.#kernel;
3118
+ }
3119
+
3120
+ /**
3121
+ * Allocate the twins once, on the first dispatch that asks, and widen them for every key the
3122
+ * provider names that has no twin yet.
3123
+ *
3124
+ * The buffers hold a record and a run per key at the layout the main pass already gave it, so a
3125
+ * twin is a second copy of two numbers rather than a new key space: the shadow kernel reads the
3126
+ * same `keys` table and writes at the same offsets into buffers of its own. That is the whole of
3127
+ * the cost — the main drawn capacity again, at 64 bytes an instance slot, plus 20 bytes of record
3128
+ * per key — and it is paid only when a provider has registered.
3129
+ */
3130
+ #mintShadowKeys(names: Iterable<string>): void {
3131
+ let shadow = this.#shadow;
3132
+ if (shadow === undefined) {
3133
+ const args = storageAttribute(IndirectStorageBufferAttribute, "uint", DRAW_ARGS_WORDS);
3134
+ const drawn = storageAttribute(StorageInstancedBufferAttribute, "mat4", 1);
3135
+ shadow = { args, drawn, held: new Set(), keys: new Map() };
3136
+ this.#shadow = shadow;
3137
+ this.#version += 1;
3138
+ }
3139
+ for (const name of names) {
3140
+ const index = this.#keysByName.get(name);
3141
+ // A name with no main key has nothing to twin; that is the owner's to fix, not this method's.
3142
+ if (index === undefined || shadow.keys.has(name)) continue;
3143
+ shadow.keys.set(name, index);
3144
+ shadow.held.add(index);
3145
+ this.#writeShadowKey(index);
3146
+ }
3147
+ // Widened to the main extent whether or not a key opened: the twin clear dispatch is one thread
3148
+ // per key, so a narrower twin args buffer would have it read a record that is not there.
3149
+ this.#growShadow(shadow, this.#regions.length * DRAW_ARGS_WORDS, this.#drawnCapacity);
3150
+ }
3151
+
3152
+ /**
3153
+ * Widen the twins to the main buffers' own extent, by doubling as `#growOf` does. A shadow twin is
3154
+ * a structural event exactly when its main key is one — a new pipeline, and a version bump, so a
3155
+ * mesh dressed against the old attributes is re-dressed.
3156
+ */
3157
+ #growShadow(shadow: IShadowBuffers, words: number, slots: number): void {
3158
+ if (shadow.args.count >= words && shadow.drawn.count >= slots) return;
3159
+ this.#shadow = {
3160
+ args: growBuffer(shadow.args, words, (count) =>
3161
+ storageAttribute(IndirectStorageBufferAttribute, "uint", count, Uint32Array),
3162
+ ),
3163
+ drawn: growBuffer(shadow.drawn, slots, (count) =>
3164
+ storageAttribute(StorageInstancedBufferAttribute, "mat4", count),
3165
+ ),
3166
+ held: shadow.held,
3167
+ keys: shadow.keys,
3168
+ };
3169
+ // The attributes the twin kernel is built from changed, so it is a new pipeline: a structural
3170
+ // event, like every other grow in this class.
3171
+ this.#shadowKernel = undefined;
3172
+ this.#version += 1;
3173
+ // Records written while the twin was narrower than the key table went nowhere; the copy above
3174
+ // carried every word that was in range, and this puts the rest back.
3175
+ for (const index of shadow.held) this.#writeShadowKey(index);
3176
+ }
3177
+
3178
+ /**
3179
+ * One twin's record, which is its main record's geometry and run with the count left at zero. A key
3180
+ * with no twin writes nothing, and a regrow that moved the main run moves this one with it —
3181
+ * `#writeKey` is the only writer of a main record, and it calls this.
3182
+ */
3183
+ #writeShadowKey(index: number): void {
3184
+ const shadow = this.#shadow;
3185
+ const region = this.#regions[index];
3186
+ if (shadow === undefined || region === undefined || shadow.held.has(index) === false) return;
3187
+ const args = shadow.args.array as Uint32Array;
3188
+ const record = region.argsIndex * DRAW_ARGS_WORDS;
3189
+ args[record] = region.indexCount;
3190
+ args[record + 1] = 0;
3191
+ args[record + 2] = 0;
3192
+ args[record + 3] = 0;
3193
+ args[record + 4] = region.start;
3194
+ shadow.args.needsUpdate = true;
3195
+ // The twin's mark on the main key record, which the shadow kernel reads to know a level casts.
3196
+ const buffers = this.#buffers;
3197
+ if (buffers === undefined) return;
3198
+ (buffers.keys.array as Float32Array)[index * VEC4_WORDS + 3] = 1;
3199
+ addRange(buffers.keys, index * VEC4_WORDS, VEC4_WORDS);
3200
+ buffers.keys.needsUpdate = true;
3201
+ }
3202
+
3203
+ /**
3204
+ * The shadow twin of {@link #buildKernel}: the same clear and the same per-placement selection,
3205
+ * reading the same source, gate, level and key tables and writing the twin records and runs.
3206
+ *
3207
+ * Two branches are the level's rather than the camera's — the planes it tests against and its
3208
+ * texel gate — and one is the level's base, which floors the main pass's own level at the shape the
3209
+ * cluster path hands it. A level whose key has no minted twin (`keys.w`) casts nothing.
3210
+ */
3211
+ #buildShadowKernel(): { readonly cull: unknown; readonly clear: unknown } | undefined {
3212
+ const buffers = this.#buffers;
3213
+ const shadow = this.#shadow;
3214
+ if (buffers === undefined || shadow === undefined) return undefined;
3215
+ const source = nodes(storage(buffers.source, PlacementStruct, buffers.source.count));
3216
+ const drawn = nodes(storage(shadow.drawn, "mat4", shadow.drawn.count));
3217
+ const argsPlain = nodes(storage(shadow.args, "uint", shadow.args.count));
3218
+ const argsAtomic = nodes(storage(shadow.args, "uint", shadow.args.count).toAtomic());
3219
+ const keys = nodes(storage(buffers.keys, "vec4", buffers.keys.count));
3220
+ const locals = nodes(storage(buffers.locals, "mat4", buffers.locals.count));
3221
+ const gates = nodes(storage(buffers.gates, "vec4", buffers.gates.count));
3222
+ const levels = nodes(storage(buffers.levels, "vec4", buffers.levels.count));
3223
+ const counts = nodes(this.#counts);
3224
+ // The main pass's own eye and bias, which this frame's main dispatch set: a shadow map draws each
3225
+ // placement at the level the main pass draws it, as the cluster path does.
3226
+ const eye = nodes(this.#eye);
3227
+ const bias = nodes(this.#lodBias);
3228
+ const gate = nodes(this.#shadowGate);
3229
+ const base = nodes(this.#shadowBase);
3230
+ const planes = this.#shadowPlaneUniforms.map((plane) => nodes(plane));
3231
+ // Measuring doubles the clear: the second thread per key zeroes that key's word of the
3232
+ // measured-occlusion tally, which is why the args buffer is sized for it (see `argsWords`).
3233
+ // A run that is not measuring never pays the second thread.
3234
+ const clearWidth = this.#occlusion === "off" ? 1 : 2;
3235
+ const clear = Fn(() => {
3236
+ If(instanceIndex.greaterThanEqual(counts.w.mul(clearWidth)), () => Return());
3237
+ If(instanceIndex.lessThan(counts.w), () => {
3238
+ const key = keys.element(instanceIndex);
3239
+ argsPlain.element(key.z.mul(DRAW_ARGS_WORDS).add(1)).assign(int(0));
3240
+ });
3241
+ If(instanceIndex.greaterThanEqual(counts.w), () => {
3242
+ argsPlain
3243
+ .element(
3244
+ nodes(counts.w.mul(DRAW_ARGS_WORDS)).add(
3245
+ nodes(float(instanceIndex).sub(counts.w).floor()),
3246
+ ),
3247
+ )
3248
+ .assign(int(0));
3249
+ });
3250
+ })().compute(Math.max(1, buffers.keys.count * clearWidth));
3251
+ const cull = Fn(() => {
3252
+ If(instanceIndex.greaterThanEqual(counts.x), () => Return());
3253
+ const placement = source.element(instanceIndex);
3254
+ const centre = placement.get("centre");
3255
+ const matrix = placement.get("matrix");
3256
+ const slot = placement.get("info").x;
3257
+ If(slot.lessThan(0.0), () => Return());
3258
+ If(slot.greaterThanEqual(counts.y), () => Return());
3259
+ const radius = centre.w;
3260
+ for (const plane of planes)
3261
+ If(plane.dot(centre.xyz).lessThan(radius.negate()), () => Return());
3262
+ // Sub-texel, the level's own gate rather than a camera's: a caster this map cannot resolve
3263
+ // casts no shadow a fragment could tell from ground cover.
3264
+ If(gate.greaterThan(0.0).and(radius.mul(2.0).lessThan(gate)), () => Return());
3265
+ const asset = gates.element(slot);
3266
+ const distance = length(vec3(centre.x.sub(eye.x), 0.0, centre.z.sub(eye.z)));
3267
+ If(asset.w.mod(2.0).greaterThan(0.5).and(distance.greaterThan(asset.z)), () => Return());
3268
+ // The main pass's own biased distance and level; see `shadowLevel`, which the reference runs.
3269
+ const lodDistance = nodes(distance).mul(bias as never);
3270
+ const level = int(0).toVar();
3271
+ const scale = abs(placement.get("info").y);
3272
+ Loop(
3273
+ { start: int(1), end: asset.y, type: "int", condition: "<" },
3274
+ ({ i }: { i: unknown }) => {
3275
+ const candidate = levels.element(asset.x.add(i as never));
3276
+ const threshold = nodes(candidate.x).toVar();
3277
+ If(candidate.w.greaterThan(0.5), () => {
3278
+ const previous = levels.element(asset.x.add(i as never).sub(1)).x;
3279
+ const floor = previous.add(abs(previous).mul(GATE_STEP));
3280
+ threshold.assign(max(floor, candidate.x.mul(scale)));
3281
+ });
3282
+ // A level the prewarm has minted no key for is not taken, as in the main kernel: see
3283
+ // `drawableLevel`, which the reference mirrors.
3284
+ If(lodDistance.greaterThan(threshold), () => {
3285
+ If(candidate.z.greaterThan(0.5), () => {
3286
+ level.assign(i as never);
3287
+ });
3288
+ });
3289
+ },
3290
+ );
3291
+ // A level casts when its first key has a minted twin (`keys.w`). The shape is the last
3292
+ // casting level in `[0, max(level, base)]`: a placement whose own level casts nothing casts
3293
+ // with the coarsest one below it that does, and the map's base floors it, clamped to the last
3294
+ // level that casts, so a coarse map never asks for a twin that was not minted. None: no cast.
3295
+ const castsAt = (index: unknown): unknown => {
3296
+ const entry = levels.element(asset.x.add(index as never));
3297
+ return nodes(entry.z.greaterThan(0.5)).and(keys.element(entry.y).w.greaterThan(0.5));
3298
+ };
3299
+ // Authored LODs past castLevels cast nothing, matching WorldCells#castLevelOf.
3300
+ If(asset.w.greaterThan(1.5).and(nodes(castsAt(level)).not()), () => Return());
3301
+ const shape = int(-1).toVar();
3302
+ Loop(
3303
+ {
3304
+ start: int(0),
3305
+ end: nodes(
3306
+ max(level as never, int(min(base as never, asset.y.sub(1.0) as never)) as never),
3307
+ ).add(1),
3308
+ type: "int",
3309
+ condition: "<",
3310
+ },
3311
+ ({ i }: { i: unknown }) => {
3312
+ If(castsAt(i) as never, () => {
3313
+ shape.assign(i as never);
3314
+ });
3315
+ },
3316
+ );
3317
+ If(shape.lessThan(0), () => Return());
3318
+ const at = levels.element(asset.x.add(shape));
3319
+ Loop({ start: int(0), end: at.z, type: "int", condition: "<" }, ({ i }: { i: unknown }) => {
3320
+ const keyIndex = at.y.add(i as never);
3321
+ const key = keys.element(keyIndex);
3322
+ const taken = nodes(
3323
+ atomicAdd(argsAtomic.element(key.z.mul(DRAW_ARGS_WORDS).add(1)), int(1)),
3324
+ );
3325
+ If(taken.toFloat().lessThan(key.y), () => {
3326
+ drawn.element(key.x.add(taken)).assign(matrix.mul(locals.element(keyIndex)));
3327
+ });
3328
+ });
3329
+ })().compute(Math.max(1, buffers.source.count));
3330
+ clear.setName("worldGpuSceneShadowClear");
3331
+ cull.setName("worldGpuSceneShadowCull");
3332
+ this.#shadowKernel = { clear, cull };
3333
+ return this.#shadowKernel;
3334
+ }
3335
+
3336
+ #report(renderer: IRendererLike): void {
3337
+ this.#reported = true;
3338
+ const report = this.report();
3339
+ const name =
3340
+ "log" in renderer ? (renderer.log as ((message: string) => void) | undefined) : undefined;
3341
+ // The GPU-selected counts ride the line only once a tally has landed. `instances` above is what
3342
+ // the scene holds; `gpuInstances` is what the GPU drew, main pass only.
3343
+ const tally =
3344
+ report.gpuTriangles === undefined
3345
+ ? ""
3346
+ : ` gpuInstances=${String(report.gpuInstances)} gpuTriangles=${String(report.gpuTriangles)}`;
3347
+ const line =
3348
+ `TN_WORLD_GPU_SCENE ${report.on ? "on" : "off"} reason=${report.reason || "none"} ` +
3349
+ `instances=${String(report.instances)} keys=${String(report.keys)} ` +
3350
+ `dressed=${String(this.#census.dressed)}/${String(this.#census.meshes)}${tally}`;
3351
+ if (typeof name === "function") name(line);
3352
+ else console.info(line);
3353
+ }
3354
+ }