@viggle/splat-engine-three 0.1.1 → 0.3.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.
- package/CHANGELOG.md +58 -0
- package/README.md +158 -20
- package/dist/chunks/chunk-2GKWT24B.js +23182 -0
- package/dist/chunks/chunk-2GKWT24B.js.map +7 -0
- package/dist/index.js +235 -3
- package/dist/types/anim/animation-conversion.d.ts +2 -2
- package/dist/types/anim/keyframe-splines.d.ts +17 -41
- package/dist/types/animation.d.ts +84 -28
- package/dist/types/armature.d.ts +280 -2
- package/dist/types/character.d.ts +120 -2
- package/dist/types/effects/index.d.ts +12 -0
- package/dist/types/effects/outlines/outline-effect.d.ts +98 -0
- package/dist/types/effects/outlines/outline-shaders.d.ts +14 -0
- package/dist/types/effects/pixelart/pixelart-effect.d.ts +152 -0
- package/dist/types/effects/pixelart/pixelart-shaders.d.ts +31 -0
- package/dist/types/effects/postfx/base-capturing-pass.d.ts +109 -0
- package/dist/types/effects/postfx/camera-frame.d.ts +103 -0
- package/dist/types/effects/postfx/frame-renderer.d.ts +32 -0
- package/dist/types/effects/postfx/frame-shaders.d.ts +19 -0
- package/dist/types/effects/postfx/mask.d.ts +44 -0
- package/dist/types/effects/postfx/postfx.d.ts +144 -0
- package/dist/types/effects/postfx/program.d.ts +74 -0
- package/dist/types/effects/postfx/uniforms.d.ts +24 -0
- package/dist/types/effects/postfx/webgl-program.d.ts +6 -0
- package/dist/types/effects/postfx/webgpu-program.d.ts +3 -0
- package/dist/types/effects/vfx/data-types.d.ts +100 -0
- package/dist/types/effects/vfx/index.d.ts +37 -0
- package/dist/types/effects/vfx/json-vfx-prefab.d.ts +94 -0
- package/dist/types/effects/vfx/layer-renderer.d.ts +118 -0
- package/dist/types/effects/vfx/layers/mesh.d.ts +124 -0
- package/dist/types/effects/vfx/layers/particle.d.ts +90 -0
- package/dist/types/effects/vfx/layers/shader.d.ts +130 -0
- package/dist/types/effects/vfx/layers/shared.d.ts +40 -0
- package/dist/types/effects/vfx/layers/sprite.d.ts +45 -0
- package/dist/types/effects/vfx/pool.d.ts +51 -0
- package/dist/types/effects/vfx/prefab.d.ts +48 -0
- package/dist/types/effects/vfx/prewarm.d.ts +17 -0
- package/dist/types/effects/vfx/stage.d.ts +115 -0
- package/dist/types/effects/vfx/webgpu-register.d.ts +2 -0
- package/dist/types/effects/webgpu-register.d.ts +2 -0
- package/dist/types/engine.d.ts +18 -0
- package/dist/types/environment.d.ts +96 -8
- package/dist/types/index.d.ts +35 -6
- package/dist/types/loader/animation/animation-glb.d.ts +4 -4
- package/dist/types/loader/character/load.d.ts +6 -1
- package/dist/types/loader/environment/lod-bundle.d.ts +123 -0
- package/dist/types/loader/environment/spz-decode.d.ts +88 -0
- package/dist/types/loader/environment/spz.d.ts +28 -0
- package/dist/types/loader/shared/asset-fetch.d.ts +11 -0
- package/dist/types/loader/shared/asset-loader.d.ts +86 -0
- package/dist/types/loader/shared/bin-cache.d.ts +41 -14
- package/dist/types/loader/shared/decode-worker.d.ts +27 -0
- package/dist/types/loader/shared/glb.d.ts +30 -0
- package/dist/types/loader/shared/inflate.d.ts +9 -0
- package/dist/types/loader/shared/pack-splats-task.d.ts +17 -0
- package/dist/types/loader/shared/sog-decode.d.ts +81 -0
- package/dist/types/loader/shared/sog.d.ts +17 -0
- package/dist/types/math.d.ts +198 -13
- package/dist/types/physics/ammo.d.ts +217 -0
- package/dist/types/physics/index.d.ts +11 -0
- package/dist/types/physics/joints.d.ts +206 -0
- package/dist/types/physics/physics-world.d.ts +194 -0
- package/dist/types/physics/rigid-body.d.ts +361 -0
- package/dist/types/presets/camera/camera-preset.d.ts +43 -0
- package/dist/types/presets/camera/third-person-camera.d.ts +63 -0
- package/dist/types/presets/character/body-shape.d.ts +109 -0
- package/dist/types/presets/character/character-reveal.d.ts +90 -0
- package/dist/types/presets/character/socket-loadout.d.ts +61 -0
- package/dist/types/presets/index.d.ts +13 -0
- package/dist/types/presets/vfx/mesh-flash.d.ts +51 -0
- package/dist/types/presets/visual/bone-overlay.d.ts +57 -0
- package/dist/types/proxy/environment-input.d.ts +30 -0
- package/dist/types/proxy/environment-source.d.ts +39 -0
- package/dist/types/proxy/proxy-debug.d.ts +106 -0
- package/dist/types/proxy/splat-source.d.ts +42 -0
- package/dist/types/proxy/voxelizer.d.ts +383 -0
- package/dist/types/relight/backend.d.ts +101 -0
- package/dist/types/relight/index.d.ts +6 -0
- package/dist/types/relight/relight-pass.d.ts +367 -0
- package/dist/types/relight/relight-placeholder.d.ts +2 -0
- package/dist/types/relight/relight-shaders.d.ts +4 -0
- package/dist/types/relight/shadow-bias.d.ts +26 -0
- package/dist/types/relight/splat-relight.d.ts +760 -0
- package/dist/types/relight/webgl-backend.d.ts +3 -0
- package/dist/types/relight/webgpu/backend.d.ts +3 -0
- package/dist/types/relight/webgpu-register.d.ts +2 -0
- package/dist/types/scene.d.ts +291 -0
- package/dist/types/skeletal/animation-player.d.ts +31 -3
- package/dist/types/skeletal/body-parts.d.ts +55 -0
- package/dist/types/skeletal/ragdoll-config.d.ts +115 -0
- package/dist/types/skeletal/ragdoll.d.ts +283 -0
- package/dist/types/skeletal/skeleton.d.ts +9 -2
- package/dist/types/splat/backend.d.ts +2 -0
- package/dist/types/splat/color-modifier.d.ts +78 -0
- package/dist/types/splat/cut-groups.d.ts +27 -0
- package/dist/types/splat/relight-binding.d.ts +39 -0
- package/dist/types/splat/reveal-bake.d.ts +43 -0
- package/dist/types/splat/reveal-look.d.ts +64 -0
- package/dist/types/splat/splat-mesh.d.ts +1 -0
- package/dist/types/splat/splat.d.ts +154 -0
- package/dist/types/splat/webgl/shaders.d.ts +5 -1
- package/dist/types/splat/webgl/splat-mesh.d.ts +4 -0
- package/dist/types/splat/webgpu/radix-sort.d.ts +3 -0
- package/dist/types/splat/webgpu/splat-mesh.d.ts +23 -0
- package/dist/types/three/splat-character.d.ts +28 -0
- package/dist/types/three/spz-loader.d.ts +35 -0
- package/dist/types/types.d.ts +6 -0
- package/dist/webgpu.js +1137 -154
- package/dist/webgpu.js.map +4 -4
- package/package.json +6 -2
- package/dist/chunks/chunk-WN5WBKM4.js +0 -8606
- package/dist/chunks/chunk-WN5WBKM4.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';
|