@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.
- package/capabilities.json +1505 -79
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-CljaDv4D.d.ts → game-Bj8G1wmD.d.ts} +102 -11
- package/dist/hot.d.ts +4 -4
- package/dist/index.d.ts +712 -118
- package/dist/index.js +12423 -4955
- package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
- package/dist/playtest.d.ts +6 -10
- package/dist/playtest.js +47 -24
- package/dist/react-css.d.ts +62 -0
- package/dist/react-css.js +591 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +766 -73
- package/dist/world.js +9307 -3543
- package/gpl/recipes/export_world.py +18 -1
- package/mcp/blender-server.mjs +7 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +2 -2
- package/mcp/servers.mjs +4 -4
- package/package.json +15 -9
- package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
- package/patches/three@0.185.1.patch +6594 -700
- package/scripts/apply-three-patch.mjs +62 -4
- package/src/animation-blend.ts +264 -0
- package/src/animation-composition.ts +362 -0
- package/src/animation-layers.ts +260 -0
- package/src/animation-root-motion.ts +283 -0
- package/src/animation.ts +896 -0
- package/src/assets.ts +1303 -0
- package/src/atmosphere/index.ts +335 -0
- package/src/atmosphere/luts.ts +298 -0
- package/src/atmosphere/params.ts +323 -0
- package/src/audio.ts +912 -0
- package/src/billboard.ts +124 -0
- package/src/bone-lengths.ts +157 -0
- package/src/camera-shake.ts +116 -0
- package/src/canvas-layer.ts +47 -0
- package/src/clip-audit.ts +401 -0
- package/src/clustered-batch.ts +492 -0
- package/src/clustered-mesh.ts +638 -0
- package/src/compute-driven.ts +176 -0
- package/src/compute-timing.ts +318 -0
- package/src/config.ts +593 -0
- package/src/debug.ts +82 -0
- package/src/engine-render-hook.ts +25 -0
- package/src/entities.ts +79 -0
- package/src/entity-snapshot.ts +53 -0
- package/src/flight.ts +683 -0
- package/src/fluid-field.ts +748 -0
- package/src/fluid-particles.ts +1253 -0
- package/src/frame-budget.ts +1368 -0
- package/src/game.ts +2390 -0
- package/src/geometry-capture.ts +1098 -0
- package/src/gpu-class.ts +160 -0
- package/src/gpu-frame-observation.ts +424 -0
- package/src/gpu-readback.ts +143 -0
- package/src/gpu-scene-bvh.ts +464 -0
- package/src/grounding.ts +100 -0
- package/src/hot.ts +161 -0
- package/src/import-meta.d.ts +13 -0
- package/src/index.ts +1536 -0
- package/src/input.ts +690 -0
- package/src/instanced-batch-lod.ts +283 -0
- package/src/instanced-batch.ts +274 -0
- package/src/interpolation.ts +129 -0
- package/src/launch-diagnostics.ts +161 -0
- package/src/loop.ts +564 -0
- package/src/matrix-world.ts +245 -0
- package/src/merge-parts.ts +812 -0
- package/src/model-lod.ts +1315 -0
- package/src/net-protocol.ts +333 -0
- package/src/net-session.ts +477 -0
- package/src/net.ts +80 -0
- package/src/ocean/fft.ts +72 -0
- package/src/ocean/spectral.ts +728 -0
- package/src/particle-significance.ts +102 -0
- package/src/particles.ts +648 -0
- package/src/path-follow.ts +175 -0
- package/src/picking.ts +250 -0
- package/src/pipeline-census.ts +1566 -0
- package/src/platform.ts +210 -0
- package/src/playtest.ts +839 -0
- package/src/pointer-events.ts +411 -0
- package/src/pose-measure.ts +435 -0
- package/src/profiling/FrameCounters.ts +231 -0
- package/src/profiling/Spans.ts +548 -0
- package/src/profiling/opacity-convention.ts +21 -0
- package/src/profiling/render-list-validate.ts +175 -0
- package/src/profiling/render-trap-audit.ts +84 -0
- package/src/profiling/scene-warning.ts +190 -0
- package/src/profiling/span-probes.ts +191 -0
- package/src/profiling/unlit-foliage-warning.ts +149 -0
- package/src/projection-apply.ts +1529 -0
- package/src/projection-marker.ts +142 -0
- package/src/projection-plan.ts +1258 -0
- package/src/projection-skinned.ts +419 -0
- package/src/projection-stability.ts +409 -0
- package/src/projection-uniform.ts +328 -0
- package/src/random.ts +41 -0
- package/src/react-css.ts +604 -0
- package/src/react-glyphs.ts +114 -0
- package/src/react-host.ts +576 -0
- package/src/react-layout.ts +265 -0
- package/src/react.ts +60 -0
- package/src/render/alpha-antialiasing.ts +159 -0
- package/src/render/batched-velocity.ts +126 -0
- package/src/render/chain.ts +1021 -0
- package/src/render/daylight.ts +189 -0
- package/src/render/depth-pyramid.ts +596 -0
- package/src/render/foliage-alpha.ts +166 -0
- package/src/render/material-key.ts +60 -0
- package/src/render/mesh-pool.ts +144 -0
- package/src/render/probe-volume.ts +1668 -0
- package/src/render/resolution-subrect.ts +253 -0
- package/src/render/velocity.ts +442 -0
- package/src/render/virtual-shadow-pages.ts +827 -0
- package/src/render/virtual-shadow-partial.ts +174 -0
- package/src/render/virtual-shadow.ts +3330 -0
- package/src/render/world-impostor-surface.ts +722 -0
- package/src/render/world-impostor.ts +558 -0
- package/src/render-camera-cull.ts +441 -0
- package/src/render-pass-budget.ts +501 -0
- package/src/renderProjection.ts +758 -0
- package/src/renderer-config.ts +127 -0
- package/src/renderer.ts +1847 -0
- package/src/replay-protocol.ts +85 -0
- package/src/replay.ts +205 -0
- package/src/resolution-scaler.ts +819 -0
- package/src/rig-preparation.ts +271 -0
- package/src/ripple-field.ts +432 -0
- package/src/scale.ts +109 -0
- package/src/scene.ts +239 -0
- package/src/schedule.ts +155 -0
- package/src/skeletal-mesh.ts +61 -0
- package/src/skeleton.ts +100 -0
- package/src/snow-field.ts +744 -0
- package/src/softbody-topology.ts +269 -0
- package/src/softbody.ts +516 -0
- package/src/sprite-animator.ts +222 -0
- package/src/startup-readiness.ts +386 -0
- package/src/state.ts +66 -0
- package/src/static-transform.ts +274 -0
- package/src/storage-buffer.ts +253 -0
- package/src/streaming.ts +308 -0
- package/src/target-fps.ts +92 -0
- package/src/terrain-jobs-worker.ts +17 -0
- package/src/terrain-jobs.ts +353 -0
- package/src/textures.ts +39 -0
- package/src/tracers.ts +237 -0
- package/src/ui-bridge.ts +368 -0
- package/src/ui-hit-regions.ts +380 -0
- package/src/ui-layer.ts +83 -0
- package/src/ui-state.ts +220 -0
- package/src/version.ts +2 -0
- package/src/viewport.ts +253 -0
- package/src/warmup.ts +1357 -0
- package/src/water-surface.ts +384 -0
- package/src/wave-field.ts +524 -0
- package/src/world-capabilities.ts +131 -0
- package/src/world-cell-proxy.ts +392 -0
- package/src/world-cells.ts +10564 -0
- package/src/world-gpu-scene.ts +3354 -0
- package/src/world-heightmap.ts +82 -0
- package/src/world-package.ts +469 -0
- package/src/world-passes.ts +582 -0
- package/src/world-region.ts +17 -0
- package/src/world-terrain-splat.ts +564 -0
- package/src/world-tiles.ts +3826 -0
- package/src/world-topology.ts +370 -0
- package/src/world-validate.ts +48 -0
- package/src/world.ts +805 -0
|
@@ -0,0 +1,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
|
+
}
|