@viggle/splat-engine-three 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/CHANGELOG.md +38 -0
  2. package/README.md +306 -33
  3. package/dist/chunks/chunk-BHNNSHJG.js +22298 -0
  4. package/dist/chunks/chunk-BHNNSHJG.js.map +7 -0
  5. package/dist/index.js +225 -3
  6. package/dist/types/anim/animation-conversion.d.ts +2 -2
  7. package/dist/types/anim/keyframe-splines.d.ts +17 -41
  8. package/dist/types/animation.d.ts +84 -28
  9. package/dist/types/armature.d.ts +280 -2
  10. package/dist/types/character.d.ts +163 -3
  11. package/dist/types/effects/index.d.ts +12 -0
  12. package/dist/types/effects/outlines/outline-effect.d.ts +98 -0
  13. package/dist/types/effects/outlines/outline-shaders.d.ts +14 -0
  14. package/dist/types/effects/pixelart/pixelart-effect.d.ts +152 -0
  15. package/dist/types/effects/pixelart/pixelart-shaders.d.ts +31 -0
  16. package/dist/types/effects/postfx/base-capturing-pass.d.ts +109 -0
  17. package/dist/types/effects/postfx/camera-frame.d.ts +103 -0
  18. package/dist/types/effects/postfx/frame-renderer.d.ts +32 -0
  19. package/dist/types/effects/postfx/frame-shaders.d.ts +19 -0
  20. package/dist/types/effects/postfx/mask.d.ts +44 -0
  21. package/dist/types/effects/postfx/postfx.d.ts +144 -0
  22. package/dist/types/effects/postfx/program.d.ts +74 -0
  23. package/dist/types/effects/postfx/uniforms.d.ts +24 -0
  24. package/dist/types/effects/postfx/webgl-program.d.ts +6 -0
  25. package/dist/types/effects/postfx/webgpu-program.d.ts +3 -0
  26. package/dist/types/effects/vfx/data-types.d.ts +100 -0
  27. package/dist/types/effects/vfx/index.d.ts +37 -0
  28. package/dist/types/effects/vfx/json-vfx-prefab.d.ts +94 -0
  29. package/dist/types/effects/vfx/layer-renderer.d.ts +118 -0
  30. package/dist/types/effects/vfx/layers/mesh.d.ts +124 -0
  31. package/dist/types/effects/vfx/layers/particle.d.ts +90 -0
  32. package/dist/types/effects/vfx/layers/shader.d.ts +130 -0
  33. package/dist/types/effects/vfx/layers/shared.d.ts +40 -0
  34. package/dist/types/effects/vfx/layers/sprite.d.ts +45 -0
  35. package/dist/types/effects/vfx/pool.d.ts +51 -0
  36. package/dist/types/effects/vfx/prefab.d.ts +48 -0
  37. package/dist/types/effects/vfx/prewarm.d.ts +17 -0
  38. package/dist/types/effects/vfx/stage.d.ts +115 -0
  39. package/dist/types/effects/vfx/webgpu-register.d.ts +2 -0
  40. package/dist/types/effects/webgpu-register.d.ts +2 -0
  41. package/dist/types/engine.d.ts +18 -0
  42. package/dist/types/environment.d.ts +96 -8
  43. package/dist/types/index.d.ts +36 -6
  44. package/dist/types/loader/animation/animation-glb.d.ts +4 -4
  45. package/dist/types/loader/character/load.d.ts +6 -1
  46. package/dist/types/loader/environment/lod-bundle.d.ts +123 -0
  47. package/dist/types/loader/environment/spz-decode.d.ts +88 -0
  48. package/dist/types/loader/environment/spz.d.ts +28 -0
  49. package/dist/types/loader/shared/asset-fetch.d.ts +11 -0
  50. package/dist/types/loader/shared/asset-loader.d.ts +86 -0
  51. package/dist/types/loader/shared/bin-cache.d.ts +41 -14
  52. package/dist/types/loader/shared/decode-worker.d.ts +27 -0
  53. package/dist/types/loader/shared/glb.d.ts +30 -0
  54. package/dist/types/loader/shared/inflate.d.ts +9 -0
  55. package/dist/types/loader/shared/pack-splats-task.d.ts +17 -0
  56. package/dist/types/loader/shared/sog-decode.d.ts +81 -0
  57. package/dist/types/loader/shared/sog.d.ts +17 -0
  58. package/dist/types/math.d.ts +7 -0
  59. package/dist/types/physics/ammo.d.ts +210 -0
  60. package/dist/types/physics/index.d.ts +11 -0
  61. package/dist/types/physics/joints.d.ts +157 -0
  62. package/dist/types/physics/physics-world.d.ts +193 -0
  63. package/dist/types/physics/rigid-body.d.ts +361 -0
  64. package/dist/types/presets/camera/camera-preset.d.ts +43 -0
  65. package/dist/types/presets/camera/third-person-camera.d.ts +63 -0
  66. package/dist/types/presets/character/body-shape.d.ts +109 -0
  67. package/dist/types/presets/character/character-reveal.d.ts +90 -0
  68. package/dist/types/presets/character/socket-loadout.d.ts +61 -0
  69. package/dist/types/presets/index.d.ts +13 -0
  70. package/dist/types/presets/vfx/mesh-flash.d.ts +51 -0
  71. package/dist/types/presets/visual/bone-overlay.d.ts +57 -0
  72. package/dist/types/proxy/environment-input.d.ts +30 -0
  73. package/dist/types/proxy/environment-source.d.ts +39 -0
  74. package/dist/types/proxy/proxy-debug.d.ts +106 -0
  75. package/dist/types/proxy/splat-source.d.ts +42 -0
  76. package/dist/types/proxy/voxelizer.d.ts +383 -0
  77. package/dist/types/relight/backend.d.ts +101 -0
  78. package/dist/types/relight/index.d.ts +6 -0
  79. package/dist/types/relight/relight-pass.d.ts +367 -0
  80. package/dist/types/relight/relight-placeholder.d.ts +2 -0
  81. package/dist/types/relight/relight-shaders.d.ts +4 -0
  82. package/dist/types/relight/shadow-bias.d.ts +26 -0
  83. package/dist/types/relight/splat-relight.d.ts +741 -0
  84. package/dist/types/relight/webgl-backend.d.ts +3 -0
  85. package/dist/types/relight/webgpu/backend.d.ts +3 -0
  86. package/dist/types/relight/webgpu-register.d.ts +2 -0
  87. package/dist/types/scene.d.ts +241 -0
  88. package/dist/types/skeletal/animation-player.d.ts +31 -3
  89. package/dist/types/skeletal/body-parts.d.ts +55 -0
  90. package/dist/types/skeletal/ragdoll-config.d.ts +115 -0
  91. package/dist/types/skeletal/ragdoll.d.ts +283 -0
  92. package/dist/types/skeletal/skeleton.d.ts +9 -2
  93. package/dist/types/splat/backend.d.ts +2 -0
  94. package/dist/types/splat/bone-binding.d.ts +1 -1
  95. package/dist/types/splat/color-modifier.d.ts +78 -0
  96. package/dist/types/splat/cut-groups.d.ts +27 -0
  97. package/dist/types/splat/depth-sort.d.ts +23 -5
  98. package/dist/types/splat/importance.d.ts +60 -0
  99. package/dist/types/splat/prune.d.ts +60 -0
  100. package/dist/types/splat/quality.d.ts +175 -0
  101. package/dist/types/splat/relight-binding.d.ts +39 -0
  102. package/dist/types/splat/reveal-bake.d.ts +43 -0
  103. package/dist/types/splat/reveal-look.d.ts +64 -0
  104. package/dist/types/splat/splat-mesh.d.ts +1 -0
  105. package/dist/types/splat/splat.d.ts +220 -0
  106. package/dist/types/splat/webgl/shaders.d.ts +5 -1
  107. package/dist/types/splat/webgl/splat-mesh.d.ts +6 -0
  108. package/dist/types/splat/webgpu/radix-sort.d.ts +3 -0
  109. package/dist/types/splat/webgpu/splat-mesh.d.ts +25 -0
  110. package/dist/types/three/splat-character.d.ts +56 -0
  111. package/dist/types/three/spz-loader.d.ts +35 -0
  112. package/dist/types/types.d.ts +6 -0
  113. package/dist/webgpu.js +1155 -156
  114. package/dist/webgpu.js.map +4 -4
  115. package/package.json +6 -2
  116. package/dist/chunks/chunk-MM6DJU6S.js +0 -7801
  117. package/dist/chunks/chunk-MM6DJU6S.js.map +0 -7
@@ -0,0 +1,383 @@
1
+ /**
2
+ * Splats in, a closed triangle surface out.
3
+ *
4
+ * A splat cloud is not lit geometry. Anything that needs a SURFACE from it -
5
+ * relighting, cast shadows, coverage masks - needs the same thing first: the
6
+ * boundary of the volume the splats occupy, closed, welded and cheap. This
7
+ * module is that step and nothing else. It touches no GPU, no scene and no
8
+ * PlayCanvas type, so it can be called from a worker, from a test, or from a
9
+ * build script with equal safety.
10
+ *
11
+ * WHY VOXELS AND NOT A HULL OR A POINT-CLOUD RECONSTRUCTION. The surface only
12
+ * has to be closed and roughly in the right place - it is never seen, only lit.
13
+ * A voxel grid is the one reconstruction whose error is bounded by a number the
14
+ * caller sets ({@link ProxySettings.voxelSize}) and whose output is watertight
15
+ * by construction: the boundary of a set of cells is always a closed manifold.
16
+ * Convex hulls lose every concavity, which is where the self-shadows are.
17
+ *
18
+ * CLOSED, NOT MANIFOLD. The output has no boundary edges - no holes, so no
19
+ * light leaks - but two cells that meet only along a grid edge leave that edge
20
+ * shared by four faces instead of two. A character at voxel 0.05 comes out
21
+ * with a couple of those out of some seven thousand edges. Harmless for
22
+ * lighting, and inherited from the Unity original; a collision cook or a mesh
23
+ * simplifier that assumes a manifold is where it would bite, and a collider
24
+ * wants its own simplified mesh anyway.
25
+ *
26
+ * ## The two finishes
27
+ *
28
+ * The Unity original this is ported from served two consumers from one mesh,
29
+ * and they wanted different finishes:
30
+ *
31
+ * - **Proxy (relight)** - `smooth`, voxel 0.025, dilate 0, smooth 3, no merge.
32
+ * Smoothing melts the cube staircase so the coverage silhouette and the
33
+ * self-shadows stay stable while the mesh animates. Vertices stay on the
34
+ * shared grid, so the Laplacian has neighbours to average over.
35
+ * - **Collider** - `smooth` (Surface Nets), dilate 1, a relaxation pass or
36
+ * two. One vertex per boundary cell, free to sit anywhere inside it, so a
37
+ * sloped surface comes out sloped instead of as steps. The lighter mesh.
38
+ *
39
+ * We are lighting-only, so {@link defaultProxySettings} is the RELIGHT finish.
40
+ * A collider here would want a simplified mesh built a different way anyway.
41
+ *
42
+ * `blocky` is not a lesser `smooth`. It is the exact boundary of the occupied
43
+ * cells, which is what you want when the CELLS are the thing being looked at -
44
+ * tuning voxel size against the splats. The two answer different questions.
45
+ *
46
+ * ## Which knob actually moves the fit
47
+ *
48
+ * Measured on two shipped characters, over eight yaws, by asking of every
49
+ * splat whether the view line through it hits the proxy at all - which is
50
+ * exactly the relight pass's coverage rule, since that lookup is screen-space
51
+ * with no depth test:
52
+ *
53
+ * - **`voxelSize` is the only knob that changes what the surface resolves.**
54
+ * At 0.05 m a person comes out as one lump: chin welded to chest, forearm
55
+ * welded to torso. At 0.03 the neck and the elbow gap come back, the surface
56
+ * moves from ~69 mm off the nearest splat to ~41 mm, and coverage is
57
+ * unchanged at exact. At 0.02 a sparse capture starts to leak.
58
+ * - **`dilate` buys nothing above 1 and fuses below the voxel scale.** At 1 no
59
+ * splat escapes on either character, from any of the eight yaws. At 0 a
60
+ * thousandth of them do, by up to 14 mm. At 2 the volume grows by half and
61
+ * coverage is still exact - the same number, bought twice.
62
+ * - **`smoothIterations` costs 1.4% of enclosed volume a pass and no
63
+ * coverage.** Eight passes still lose no splat.
64
+ * - **`opacityThreshold` is nearly inert on a character.** Raising it from 0
65
+ * to 0.2 drops 42% of the splats and 0.3% of the occupied cells, because the
66
+ * faint ones sit on top of bright ones. It is a knob for a capture with a
67
+ * real floater halo, not for tuning fit.
68
+ *
69
+ * So a proxy that looks melted is a voxel-size problem every time, and reading
70
+ * it as an erosion problem points at `dilate` and `smoothIterations`, which is
71
+ * the wrong end of the mesh.
72
+ *
73
+ * ## Merging and smoothing are mutually exclusive
74
+ *
75
+ * By construction, not by convention: greedy merging destroys the uniform grid
76
+ * the Laplacian averages over, leaving long thin quads whose interiors have no
77
+ * vertices to move. {@link buildProxyMesh} throws on the combination rather
78
+ * than quietly producing a surface that is neither merged well nor smoothed
79
+ * well.
80
+ *
81
+ * ## The grid is a product of its own
82
+ *
83
+ * {@link buildVoxelGrid} stops after the occupancy and hands the grid back.
84
+ * That is not a convenience wrapper - it is the half of this module a COLLIDER
85
+ * wants, and the mesh is the half it must not have. The extracted surface is
86
+ * closed but not manifold (see above), so a physics cook or a simplifier
87
+ * chokes on it, while a grid lookup - topmost occupied cell in a column is the
88
+ * floor, an occupied cell at knee height is a wall - needs no cook at all. So
89
+ * the collider reads the grid, the extraction it would throw away never runs,
90
+ * and neither consumer is paying for the other's finish. See
91
+ * `../collider/scene-collider.ts`.
92
+ *
93
+ * @module
94
+ */
95
+ /** How the occupied set is turned into triangles. */
96
+ export type ProxySurfaceStyle = 'blocky' | 'smooth';
97
+ /**
98
+ * How a splat cloud should be turned into a surface. Every field is optional;
99
+ * omitted fields take the relight finish from {@link defaultProxySettings}.
100
+ */
101
+ export interface ProxySettings {
102
+ /**
103
+ * `blocky` = the exact cell boundary, every face a square on the grid.
104
+ * `smooth` = Surface Nets: one vertex per boundary cell, free to sit
105
+ * anywhere inside it, so a sloped surface comes out sloped rather than as
106
+ * steps - truer AND lighter, and the right choice for a collider.
107
+ *
108
+ * Default `blocky`, the relight finish. See the module header.
109
+ */
110
+ surface?: ProxySurfaceStyle;
111
+ /**
112
+ * Edge length of one voxel, in metres. THE knob, and the only one that
113
+ * changes what the surface can RESOLVE. Too coarse seals gaps that should
114
+ * stay open and inflates the silhouette; too fine explodes the triangle
115
+ * count and eventually leaks, because a one-voxel dilation stops being
116
+ * enough to close the pinholes a sparse capture leaves.
117
+ *
118
+ * Default `0.025`. On a 1.9 m character that is ~76 cells of height, 25k
119
+ * triangles and an ~11 ms build. The knee is real: 0.05 fuses the neck, the
120
+ * chin and the gap between a forearm and the torso into one lump at ~69 mm
121
+ * off the nearest splat, 0.03 brings those gaps back at ~40 mm, and 0.02
122
+ * starts to leak on a sparse capture. See the module header.
123
+ */
124
+ voxelSize?: number;
125
+ /**
126
+ * Splats fainter than this do not fill a voxel. Raise it to drop the wispy
127
+ * halo of near-transparent floaters that otherwise inflates the volume well
128
+ * past the real surface. This is an ALPHA in `[0,1]`, not a logit - see
129
+ * {@link ProxyMeshInput.opacities}. Default `0.04` - low, because 0.2 drops
130
+ * the faint splats that carry a capture's thin geometry. See
131
+ * {@link defaultProxySettings}.
132
+ */
133
+ opacityThreshold?: number;
134
+ /**
135
+ * Grow the volume outward this many voxels. One step closes the pinholes a
136
+ * sparse surface leaves. For LIGHTING this wants to be at least 1, so edge
137
+ * splats land inside the coverage mask rather than on its rim. Default `1`.
138
+ *
139
+ * It is also the knob that FUSES: a dilation of one bridges every gap
140
+ * narrower than two voxels, so at a coarse voxel size it is what welds an
141
+ * arm to a torso. Raising it does not buy coverage - coverage is already
142
+ * exact at 1 on a character - it only inflates. When the proxy looks like a
143
+ * melted lump, this is not the knob; {@link voxelSize} is.
144
+ */
145
+ dilate?: number;
146
+ /**
147
+ * Laplacian relaxation passes. On `smooth` this polishes an already-smooth
148
+ * surface and 1-2 passes is plenty. On `blocky` it is the ONLY thing that
149
+ * rounds the cubes and needs more passes to do it. Every pass shrinks the
150
+ * surface slightly, which is why the volume is dilated outward first.
151
+ * Default `3`.
152
+ */
153
+ smoothIterations?: number;
154
+ /**
155
+ * Fill every column solid from the grid floor up to its lowest occupied
156
+ * voxel. A raw voxelization of an exterior capture is a SHELL: the ground is
157
+ * one voxel thick. Filling underneath turns the shell into ground with
158
+ * substance below it. Meaningless for a character or a prop, where there is
159
+ * no "underneath" - leave it off. Default `false`.
160
+ */
161
+ floorFill?: boolean;
162
+ /**
163
+ * Greedily merge coplanar faces into the largest rectangles that tile them.
164
+ * Cuts the triangle count of a blocky surface by an order of magnitude at no
165
+ * fidelity cost - the merged surface is geometrically IDENTICAL, it just
166
+ * stops spending four vertices on every one-voxel square.
167
+ *
168
+ * Rejected together with {@link smoothIterations}, and ignored entirely on
169
+ * `smooth` (Surface Nets emits no coplanar squares to merge). Default
170
+ * `false`.
171
+ */
172
+ mergeCoplanar?: boolean;
173
+ /**
174
+ * Grid ceiling, in cells. A bad voxel size on a large capture would
175
+ * otherwise allocate a pathological grid; the build coarsens the voxel size
176
+ * by 1.5x until it fits, because a coarser surface is still a usable surface
177
+ * and an out-of-memory is not. Default `4_000_000`.
178
+ */
179
+ maxVoxels?: number;
180
+ }
181
+ /**
182
+ * The relight finish: `smooth`, voxel 0.025, opacity 0.04, dilate 0, smooth 3,
183
+ * no merge.
184
+ *
185
+ * Tuned on screen against the bundled character and capture, which is the only
186
+ * test that sees what a reader sees. The measurements are what a future change
187
+ * has to beat rather than rediscover, so they are kept here next to the number
188
+ * that disagreed with them:
189
+ *
190
+ * - **`voxelSize` 0.025.** The measurement always said fine: at 0.05 a person
191
+ * comes out as one lump, chin welded to chest and forearm welded to torso,
192
+ * and the surface sits ~69 mm off the nearest splat; at 0.03 the neck and
193
+ * the elbow gap come back at ~41 mm. This briefly read 0.05 to match the
194
+ * Unity component's default, and that was the wrong thing to match - the
195
+ * Unity number was itself carried over unexamined, and agreeing with it cost
196
+ * the resolution the measurement had already paid for. 0.025 is a step finer
197
+ * again, and on the bundled character it is 7.5k voxels, 25k triangles and
198
+ * an ~11 ms build. Below 0.02 a sparse capture starts to leak.
199
+ * - **`surface` `smooth`, not `blocky`.** Surface Nets puts one vertex per
200
+ * boundary cell free to sit anywhere inside it, so a sloped surface comes
201
+ * out sloped rather than as steps. `blocky` remains the right pick for
202
+ * LOOKING at the cells - it is the exact occupied boundary - which is what
203
+ * the `voxels` preview draws.
204
+ * - **`opacityThreshold` 0.04, not 0.2.** 0.2 drops the faint splats that
205
+ * carry a capture's thin geometry, and the proxy loses surfaces the splats
206
+ * plainly have. 0.04 still filters the near-transparent halo.
207
+ * - **`dilate` 0, not 1.** One ring closes pinholes a sparse capture leaves,
208
+ * and measured, 0 lets a thousandth of the splats escape coverage by up to
209
+ * 14 mm. But a ring is a whole voxel of inflation on a surface that is
210
+ * already outside the splats, and the silhouette reads as a character
211
+ * wearing its proxy. Smoothing and the fine cell absorb what escapes.
212
+ *
213
+ * `floorFill` stays off here and is turned on per target: it is for a capture
214
+ * read as a one-voxel shell, not for a character. See
215
+ * {@link ENVIRONMENT_PROXY_DEFAULTS}.
216
+ */
217
+ export declare const defaultProxySettings: Required<ProxySettings>;
218
+ /** Integer bone indices, in whatever width the source happened to use. */
219
+ export type BoneIndexArray = Uint8Array | Uint16Array | Uint32Array | Int32Array;
220
+ /** What to voxelize. The bone arrays are optional and drive skinning when present. */
221
+ export interface ProxyMeshInput {
222
+ /** `[x,y,z] * numSplats`, in the space the caller wants the mesh in. */
223
+ positions: Float32Array;
224
+ /**
225
+ * Per-splat ALPHA in `[0,1]`, one per splat. Omit to count every splat.
226
+ *
227
+ * Our `.vsplat` containers store the LOGIT, not the alpha, so a caller
228
+ * reading `splatData.getProp('opacity')` has to push it through a sigmoid
229
+ * first - {@link alphaFromLogits} does that. Thresholding a logit against
230
+ * 0.2 would keep everything down to alpha 0.55, which is the opposite of
231
+ * what the knob is for.
232
+ */
233
+ opacities?: Float32Array;
234
+ /** `[b0,b1,b2,b3] * numSplats` rig bone indices. Omit for an unskinned build. */
235
+ boneIndices?: BoneIndexArray;
236
+ /** `[w0,w1,w2,w3] * numSplats`, matching {@link boneIndices}. */
237
+ boneWeights?: Float32Array;
238
+ }
239
+ /** Grid dimensions or a grid-space point. Plain object: this module has no vector type. */
240
+ export interface ProxyGridVec {
241
+ x: number;
242
+ y: number;
243
+ z: number;
244
+ }
245
+ /**
246
+ * The settings that shape the OCCUPANCY, which is every setting except the
247
+ * ones that only describe a finish. {@link buildVoxelGrid} takes these; the
248
+ * mesh-only knobs (`surface`, `smoothIterations`, `mergeCoplanar`) would have
249
+ * nothing to act on.
250
+ */
251
+ export type VoxelGridSettings = Pick<ProxySettings, 'voxelSize' | 'opacityThreshold' | 'dilate' | 'floorFill' | 'maxVoxels'>;
252
+ /**
253
+ * The settings that shape the SURFACE, which is the finish and nothing else.
254
+ * {@link extractSurface} takes these; the occupancy already happened by then, so
255
+ * `voxelSize`, `dilate`, `floorFill` and `opacityThreshold` have nothing left to
256
+ * act on.
257
+ */
258
+ export type SurfaceSettings = Pick<ProxySettings, 'surface' | 'smoothIterations' | 'mergeCoplanar'>;
259
+ /**
260
+ * A voxelized splat cloud, before any surface is extracted from it.
261
+ *
262
+ * What {@link buildProxyMesh} builds first and {@link buildVoxelGrid} stops at.
263
+ * A collider wants exactly this and nothing after it - see the module header.
264
+ */
265
+ export interface VoxelGrid {
266
+ /**
267
+ * `dims.x * dims.y * dims.z` bytes, 1 where the cell is solid, after
268
+ * dilation and the floor fill. Indexed `(z * dims.y + y) * dims.x + x`.
269
+ * Zero length when the run produced no grid at all.
270
+ */
271
+ occupancy: Uint8Array;
272
+ /** Grid dimensions, in cells. */
273
+ dims: ProxyGridVec;
274
+ /** World position of cell `(0,0,0)`'s low corner. */
275
+ origin: ProxyGridVec;
276
+ /** Cell edge actually used - larger than requested if the grid had to coarsen. */
277
+ voxelSize: number;
278
+ /** Cell edge asked for. Differs from {@link voxelSize} when the grid coarsened. */
279
+ requestedVoxelSize: number;
280
+ /**
281
+ * The grid hit `maxVoxels` and the cell size was raised. User-visible: a
282
+ * reader colliding with a 2.6 m grid they believe is 0.1 m has no way to
283
+ * make sense of what they are walking into.
284
+ */
285
+ coarsened: boolean;
286
+ /** Solid cells after dilation and the floor fill. */
287
+ occupiedVoxels: number;
288
+ /** Splats that passed the opacity threshold. */
289
+ splatsUsed: number;
290
+ /** Milliseconds this build took. */
291
+ buildMs: number;
292
+ }
293
+ /** The mesh, plus what the run decided along the way. */
294
+ export interface ProxyMeshResult {
295
+ /** `[x,y,z] * vertexCount`. Empty when nothing was occupied. */
296
+ positions: Float32Array;
297
+ /** `[x,y,z] * vertexCount`, area-weighted from the faces that share each vertex. */
298
+ normals: Float32Array;
299
+ /** Triangle list, 3 indices a triangle. */
300
+ indices: Uint32Array;
301
+ /**
302
+ * The same surface as {@link indices}, 4 indices a face, before
303
+ * triangulation. Both extraction styles are natively quad-based; this is
304
+ * what a wireframe should walk, because the triangulation diagonals are an
305
+ * artefact of the triangle list and not edges of the surface.
306
+ */
307
+ quads: Uint32Array;
308
+ /** `[b0,b1,b2,b3] * vertexCount` as FLOATS, or `null` when the run was unskinned. */
309
+ boneIndices: Float32Array | null;
310
+ /** `[w0,w1,w2,w3] * vertexCount`, summing to 1 per weighted vertex, or `null`. */
311
+ boneWeights: Float32Array | null;
312
+ /** Voxel size actually used - larger than requested if the grid had to coarsen. */
313
+ voxelSize: number;
314
+ /** Grid dimensions, in voxels. */
315
+ dims: ProxyGridVec;
316
+ /** World position of the grid's minimum corner, i.e. of cell `(0,0,0)`'s low corner. */
317
+ origin: ProxyGridVec;
318
+ /** Occupied voxels after dilation and floor fill. */
319
+ occupiedVoxels: number;
320
+ /** Splats that passed the opacity threshold. */
321
+ splatsUsed: number;
322
+ /** `positions.length / 3`. */
323
+ vertexCount: number;
324
+ /** `indices.length / 3`. */
325
+ triangleCount: number;
326
+ /** Milliseconds this build took. */
327
+ buildMs: number;
328
+ }
329
+ /**
330
+ * Sigmoid a `.vsplat` opacity column into the alpha
331
+ * {@link ProxyMeshInput.opacities} wants.
332
+ *
333
+ * Allocates. Call it once per capture, not once per rebuild - the voxel knobs
334
+ * are what move while tuning, and the alphas are not among them.
335
+ */
336
+ export declare function alphaFromLogits(logits: Float32Array): Float32Array;
337
+ /**
338
+ * Voxelize a splat cloud and stop there: the occupancy grid, no surface.
339
+ *
340
+ * Everything {@link buildProxyMesh} does up to the extraction - the opacity
341
+ * threshold, the padded bounds, the coarsen loop, the dilation, the floor fill
342
+ * - and none of what comes after. On a scanned room at a collider's voxel size
343
+ * the extraction is most of the build and all of it would be thrown away; see
344
+ * the module header for why a collider must not have the mesh anyway.
345
+ *
346
+ * Pure. Bone influences on `input` are ignored - a grid has no vertices to
347
+ * weight.
348
+ *
349
+ * @throws RangeError when `voxelSize <= 0`.
350
+ */
351
+ export declare function buildVoxelGrid(input: ProxyMeshInput, settings?: VoxelGridSettings): VoxelGrid;
352
+ /**
353
+ * Voxelize a splat cloud into a closed triangle surface.
354
+ *
355
+ * Pure: it reads the input arrays and returns fresh ones. The input is never
356
+ * written to and nothing is retained.
357
+ *
358
+ * @param input - Splat centres, opacity, and optionally per-splat bone
359
+ * influences. When both bone arrays are present the result carries
360
+ * per-vertex weights and can be handed straight to `ArmatureSkinAdapter`.
361
+ * @param settings - Overrides on {@link defaultProxySettings}.
362
+ * @throws RangeError when `voxelSize <= 0`, when the bone arrays are the wrong
363
+ * length, or when `mergeCoplanar` is combined with `smoothIterations > 0`.
364
+ */
365
+ export declare function buildProxyMesh(input: ProxyMeshInput, settings?: ProxySettings): ProxyMeshResult;
366
+ /**
367
+ * Turn a {@link VoxelGrid} into a surface, with no splats and no voxelization.
368
+ *
369
+ * The other half of {@link buildProxyMesh}, callable on its own so a consumer
370
+ * that already holds a grid can ask for the surface WITHOUT re-reading the
371
+ * splats. The collider is that consumer: it keeps the grid (that is what its
372
+ * queries read) and extracts a surface only when something wants to look at one
373
+ * or write one out - and because both of those come from this one call over the
374
+ * one grid, the picture and the exported file cannot be different geometry.
375
+ *
376
+ * Pure. The grid is not written to. Unskinned by construction: a grid carries no
377
+ * bone accumulation, so {@link ProxyMeshResult.boneIndices} comes back null.
378
+ *
379
+ * @param settings - only the finish matters here; `voxelSize`, `dilate`,
380
+ * `floorFill` and the rest already happened and are ignored.
381
+ * @throws RangeError when `mergeCoplanar` is combined with `smoothIterations > 0`.
382
+ */
383
+ export declare function extractSurface(grid: VoxelGrid, settings?: SurfaceSettings): ProxyMeshResult;
@@ -0,0 +1,101 @@
1
+ import type { DirectionalLight, Material, RenderTarget, Texture, Vector3 } from 'three';
2
+ import type { ProxyShadowBias } from './shadow-bias';
3
+ /**
4
+ * The renderer-facing half of the relight: the proxy's material, its render
5
+ * targets and the compose pass. Everything else - layers, cameras, lights,
6
+ * skinning, publishing - is plain three.js and shared by both renderers.
7
+ *
8
+ * Two implementations, as with the splat backends: GLSL for
9
+ * `THREE.WebGLRenderer` (the default, `webgl-backend.ts`) and TSL for
10
+ * `WebGPURenderer`, registered by the `/webgpu` entry point so the default
11
+ * entry never loads `three/webgpu`.
12
+ *
13
+ * @internal
14
+ */
15
+ export interface RelightBackend {
16
+ /**
17
+ * The material every lighting-receiving proxy is drawn with. Its output
18
+ * contract is what the compose and the splat shader assume, so it is fixed:
19
+ *
20
+ * rgb = SUM over lights of colour * N.L * attenuation * shadow
21
+ * a = 1 (the coverage mask)
22
+ *
23
+ * That is a white lambertian with NO ambient and PlayCanvas's light model:
24
+ * no 1/pi in the diffuse term, and the linear `(range - d) / range` falloff
25
+ * on point and spot lights, where three's own lights fall off by the
26
+ * inverse square with a smooth window. Shadows come from three's own shadow
27
+ * maps, so a light's `castShadow` and `shadow.*` work as they do anywhere.
28
+ * `bias` is the owning relight's key-light bias, where the backend applies
29
+ * it in the material.
30
+ */
31
+ createProxyMaterial(bias: ProxyShadowBias): Material;
32
+ /**
33
+ * A half-float RGBA target, linear-filtered: lighting exceeds 1 and must
34
+ * not clamp, and half rather than full float because some mobile GPUs
35
+ * cannot filter float32.
36
+ *
37
+ * @throws when the renderer cannot render to half float.
38
+ */
39
+ createTarget(renderer: unknown, width: number, height: number, depth: boolean): RenderTarget;
40
+ /** The compose pass. One per {@link RelightPass}. */
41
+ createComposer(): RelightComposer;
42
+ /**
43
+ * Whether the lighting texture's rows run top-down as seen through
44
+ * `uv = ndc * 0.5 + 0.5`, i.e. whether the splat lookup must mirror its
45
+ * row. A property of the renderer, measured rather than reasoned - see
46
+ * {@link RelightPass.flipY}.
47
+ */
48
+ readonly flipY: boolean;
49
+ /**
50
+ * Whether the proxy materials would read `scene.environment`, so the pass
51
+ * must clear it around the proxy render. True under `WebGLRenderer`, which
52
+ * feeds the environment to every Lambert material.
53
+ */
54
+ readonly proxyReadsEnvironment: boolean;
55
+ /**
56
+ * Make `light`'s shadow on the proxies take `bias` (shadow-bias.ts), where
57
+ * the backend does it on the light rather than in the proxy material.
58
+ */
59
+ configureKeyLight(light: DirectionalLight, bias: ProxyShadowBias): void;
60
+ }
61
+ /** Values the compose reads. See `relight-shaders.ts`. */
62
+ export interface RelightComposeParams {
63
+ /** One texel of the proxy targets, in uv. */
64
+ texelX: number;
65
+ texelY: number;
66
+ /** Tent radius over the lighting, in texels. `0` is a single tap. */
67
+ blurRadius: number;
68
+ /** Tent radius over the shadow visibility, in texels. */
69
+ shadowBlurRadius: number;
70
+ /** Ambient added back to the direct light, linear. */
71
+ ambient: Vector3;
72
+ }
73
+ /**
74
+ * The compose pass: tent-blur the raw proxy renders, un-premultiply by
75
+ * coverage, add the ambient back, and split out the shadow visibility. See
76
+ * `relight-shaders.ts` for the arithmetic.
77
+ *
78
+ * Two draws, one per output, where the PlayCanvas build writes an MRT pair
79
+ * from one: the outputs are half-resolution and the second draw is cheaper
80
+ * than the per-renderer MRT plumbing.
81
+ *
82
+ * @internal
83
+ */
84
+ export interface RelightComposer {
85
+ /**
86
+ * Write `lighting` (rgb lighting, a coverage) and `visibility` (r shadow
87
+ * visibility, g coverage) from `lit` and, when there is one, `raw` - the
88
+ * same proxies with every shadow map ignored. Without `raw` the visibility
89
+ * is 1.
90
+ */
91
+ render(renderer: unknown, lit: Texture, raw: Texture | null, lighting: RenderTarget, visibility: RenderTarget, params: RelightComposeParams): void;
92
+ dispose(): void;
93
+ }
94
+ /**
95
+ * Make the relight available under `WebGPURenderer`. Called by the
96
+ * `@viggle/splat-engine-three/webgpu` entry point.
97
+ * @internal
98
+ */
99
+ export declare function registerRelightWebGPUBackend(backend: RelightBackend): void;
100
+ /** The WebGPU backend, or `null` before the `/webgpu` entry point has loaded. @internal */
101
+ export declare function getRelightWebGPUBackend(): RelightBackend | null;
@@ -0,0 +1,6 @@
1
+ export { ENVIRONMENT_DEFAULT_LOD, ENVIRONMENT_PROXY_DEFAULTS, SplatRelight } from './splat-relight';
2
+ export type { RelightLightOptions, RelightPointLightOptions, RelightPreviewMode, RelightProxySettings, RelightProxySource, RelightTarget, RelightTargetOptions, RelightTargetParams, SplatRelightOptions, } from './splat-relight';
3
+ export type { EnvironmentRefreshMode } from './relight-pass';
4
+ export { RELIGHT_PROXY_LAYER, RELIGHT_VISIBILITY_LAYER, RelightPass } from './relight-pass';
5
+ export type { RelightConsumer, RelightPassOptions, RelightParams } from './relight-pass';
6
+ export { getRelightPlaceholder } from './relight-placeholder';