@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,367 @@
1
+ import { Mesh } from 'three';
2
+ import type { Camera, Material, Texture } from 'three';
3
+ import type { Environment } from '../environment';
4
+ import type { Scene } from '../scene';
5
+ import { Splat } from '../splat/splat';
6
+ import type { RelightBackend } from './backend';
7
+ import type { ProxyShadowBias } from './shadow-bias';
8
+ /** Per-consumer relight knobs. See {@link RelightPass.setConsumerParams}. */
9
+ export interface RelightParams {
10
+ /**
11
+ * How much of the splat's baked colour is replaced by proxy lighting.
12
+ * `0` (default) skips the texture fetch entirely, so the effect costs
13
+ * nothing until it is dialled up.
14
+ */
15
+ strength?: number;
16
+ /** Tints the received light only, never the base colour. Default white. */
17
+ tint?: {
18
+ r: number;
19
+ g: number;
20
+ b: number;
21
+ };
22
+ /** Floor under the light term so unlit faces do not go black. Default `0`. */
23
+ ambient?: number;
24
+ /**
25
+ * Cast-shadow depth, sampled from the visibility channel. `0` (default) is
26
+ * off; `1` takes a fully shadowed splat to black. Requires
27
+ * {@link RelightPassOptions.visibility}.
28
+ */
29
+ shadowStrength?: number;
30
+ /**
31
+ * Paint every splat with the outcome of its own relight sample instead of
32
+ * lighting it: magenta = no texture published, yellow = behind the camera,
33
+ * red = projects off-screen, blue = the sampled texel has no proxy coverage,
34
+ * orange = coverage found at the MIRRORED row (which convicts the y-flip
35
+ * specifically), greys = the real sample.
36
+ *
37
+ * `2` paints the shadow-visibility sample instead: greys = the ratio,
38
+ * magenta = no proxy coverage at that texel.
39
+ */
40
+ debug?: boolean | number;
41
+ }
42
+ /** Options for {@link RelightPass.create}. */
43
+ export interface RelightPassOptions {
44
+ /**
45
+ * Lighting-texture size as a fraction of the canvas. Default `0.5`.
46
+ * Lighting is low-frequency and is sampled once per splat rather than per
47
+ * pixel, so half resolution is normally indistinguishable and costs a
48
+ * quarter of the bandwidth. Settable later via
49
+ * {@link RelightPass.resolutionScale}.
50
+ */
51
+ resolutionScale?: number;
52
+ /**
53
+ * The proxy brightness that counts as "normally lit". Sampled lighting is
54
+ * divided by this, so `strength` changes lighting CONTRAST rather than
55
+ * overall brightness. Default `1`.
56
+ */
57
+ referenceLuminance?: number;
58
+ /**
59
+ * Run the 3x3 tent blur. Default `true`. This is what keeps the lighting
60
+ * temporally stable while the proxy animates; turn it off only to see the
61
+ * raw bake.
62
+ *
63
+ * Shorthand for the two radii below: `true` is 1 on each, `false` is 0.
64
+ * Whichever of the three is given last wins.
65
+ */
66
+ blur?: boolean;
67
+ /**
68
+ * Radius of the tent over the LIGHTING, in texels of the proxy target.
69
+ * Default `1`, the original tent; `0` is a single tap. See the compose
70
+ * shader's header.
71
+ */
72
+ blurRadius?: number;
73
+ /**
74
+ * Radius of the tent over the SHADOW-VISIBILITY channel, in texels of the
75
+ * proxy target. Default `1`. Inert unless `visibility` is on.
76
+ */
77
+ shadowBlurRadius?: number;
78
+ /**
79
+ * Allocate the second proxy draw that makes the shadow-visibility channel
80
+ * work. Default `false`, because it costs a second proxy render per frame.
81
+ * Without it `shadowStrength` is inert and the visibility channel reads a
82
+ * constant 1.
83
+ */
84
+ visibility?: boolean;
85
+ /**
86
+ * Camera the lighting texture is rendered from. Default `scene.camera`. It
87
+ * must be the camera the splats are viewed through - the lookup is
88
+ * screen-space.
89
+ */
90
+ mainCamera?: Camera;
91
+ /** See {@link EnvironmentRefreshMode}. Default `auto`. */
92
+ environmentRefresh?: EnvironmentRefreshMode;
93
+ /**
94
+ * The owning relight's key-light bias, which the proxy material reads
95
+ * under WebGL. Default: a zero bias of the pass's own. @internal
96
+ */
97
+ shadowBias?: ProxyShadowBias;
98
+ }
99
+ /**
100
+ * When environment splats pick up a changed lighting texture.
101
+ *
102
+ * In the PlayCanvas build an environment keeps the colour its last work-buffer
103
+ * copy computed, and this mode decides when it re-copies. This port has no
104
+ * work buffer to keep: every splat - environments included - samples the live
105
+ * lighting texture each frame it draws, so environments are always current
106
+ * and all three modes light them the same way. The mode is kept so code
107
+ * written against the PlayCanvas build carries over.
108
+ *
109
+ * - `auto` - the PlayCanvas default.
110
+ * - `always` - every frame.
111
+ * - `never` - only on {@link RelightPass.invalidateEnvironments}.
112
+ */
113
+ export type EnvironmentRefreshMode = 'auto' | 'always' | 'never';
114
+ /** Something whose relight knobs can be overridden. */
115
+ export type RelightConsumer = Splat | Environment;
116
+ /**
117
+ * The three.js layer the lit proxies render on. Proxies live on it ALONE, so
118
+ * no app camera on the default layer 0 ever draws one. A light reaches the
119
+ * proxies when it is enabled on this layer too - see {@link RelightPass.lightLayerIds}.
120
+ */
121
+ export declare const RELIGHT_PROXY_LAYER = 29;
122
+ /** The layer the unshadowed twins render on, for the shadow-visibility channel. */
123
+ export declare const RELIGHT_VISIBILITY_LAYER = 28;
124
+ /**
125
+ * Screen-space relighting of gaussian splats from a proxy mesh.
126
+ *
127
+ * A proxy mesh of the same subject - a voxelized shell - is rendered with
128
+ * three.js's real lights into an offscreen half-resolution texture. Every
129
+ * splat then samples the texel it projects to and blends that lighting over
130
+ * its own baked appearance.
131
+ *
132
+ * Screen-space and not per-splat N.L on purpose: every splat along a view ray
133
+ * reads the SAME texel, so overlapping semi-transparent splats agree and the
134
+ * per-frame depth re-sort cannot expose a contrast between them. The cost is
135
+ * view dependence - you see the shading of the surfaces that face you.
136
+ *
137
+ * ── The pipeline ──────────────────────────────────────────────────────────
138
+ *
139
+ * 1. The app's three.js scene is rendered through a copy of the main camera
140
+ * that sees only {@link RELIGHT_PROXY_LAYER}, into `_litRT`, with the
141
+ * backend's proxy material (white lambertian, no ambient, PlayCanvas's
142
+ * light model): rgb = sum over lights of `colour * N.L * attenuation *
143
+ * shadow`, a = 1 (the coverage mask). Only lights enabled on that layer
144
+ * take part, and the scene's background is held off for the duration.
145
+ * 2. Optionally the same through {@link RELIGHT_VISIBILITY_LAYER}, where a
146
+ * twin of every proxy with `receiveShadow = false` lives, into `_rawRT`:
147
+ * the same sum with every shadow map ignored.
148
+ * 3. The compose turns those into `lightingTexture` (rgb = lighting, a =
149
+ * coverage) and `visibilityTexture` (r = visibility, g = coverage),
150
+ * applying the tent blur, un-premultiplying by coverage, and adding the
151
+ * scene ambient back in.
152
+ * 4. The pair, plus the view-projection they were rendered with, is
153
+ * published to every live splat in the scene through its
154
+ * {@link SplatRelightBinding}.
155
+ *
156
+ * ── No frame lag ──────────────────────────────────────────────────────────
157
+ * The PlayCanvas build computes splat colour before its cameras render, so a
158
+ * splat there samples the texture rendered the frame before. Here the whole
159
+ * pass runs in the scene's `preRender`, before the main render that draws the
160
+ * splats, so a splat samples THIS frame's lighting.
161
+ *
162
+ * ── Why two draws and not MRT on the proxy ────────────────────────────────
163
+ * Lighting comes from three's own light loop, which writes exactly one output.
164
+ * The visibility ratio is instead recovered from a second draw of the same
165
+ * geometry with `receiveShadow = false`, which is arithmetically identical -
166
+ * see `relight-shaders.ts`.
167
+ *
168
+ * ── Shadows ───────────────────────────────────────────────────────────────
169
+ * `renderer.shadowMap.enabled` is switched on for the proxy draws and put back
170
+ * after, so the relight's shadows never change how the app's own meshes
171
+ * compile. Shadow casters are gathered by the rendering camera's layers in
172
+ * both renderers, so only proxies cast into the lighting - the app's meshes
173
+ * on layer 0 do not shadow the splats.
174
+ *
175
+ * Built per scene, never as a module global.
176
+ *
177
+ * Internal. Consumers use {@link SplatRelight}.
178
+ */
179
+ export declare class RelightPass {
180
+ /** The layer lit proxies render on. See {@link RELIGHT_PROXY_LAYER}. */
181
+ readonly proxyLayerId = 29;
182
+ /**
183
+ * Every layer a light must be enabled on for the proxies to be lit by it,
184
+ * beside whichever layers it lights the app's meshes on.
185
+ */
186
+ readonly lightLayerIds: readonly number[];
187
+ /** The material lighting-receiving proxies are drawn with. See {@link RelightBackend.createProxyMaterial}. */
188
+ readonly proxyMaterial: Material;
189
+ /**
190
+ * The material of a proxy that casts into the shadow maps but is not drawn
191
+ * into the lighting: it writes neither colour nor depth, so the lit render
192
+ * passes through it while the depth-only shadow render still sees it.
193
+ */
194
+ readonly casterMaterial: Material;
195
+ private readonly _scene;
196
+ private readonly _renderer;
197
+ private readonly _backend;
198
+ private readonly _mainCamera;
199
+ private readonly _camera;
200
+ private readonly _composer;
201
+ private _litRT;
202
+ private _rawRT;
203
+ private _lightingRT;
204
+ private _visibilityRT;
205
+ private _rtWidth;
206
+ private _rtHeight;
207
+ /** Registered proxies -> their unshadowed twin, when visibility is on. */
208
+ private readonly _proxies;
209
+ private _resolutionScale;
210
+ private _referenceLuminance;
211
+ private _blurRadius;
212
+ private _shadowBlurRadius;
213
+ private readonly _visibility;
214
+ private _environmentRefresh;
215
+ private _flipY;
216
+ private _enabled;
217
+ private _destroyed;
218
+ private _framesRendered;
219
+ private _environmentRefreshFrames;
220
+ /** Scene-wide defaults, overridden per {@link Splat} by `setConsumerParams`. */
221
+ private readonly _defaults;
222
+ /** What every splat without an override reads. */
223
+ private readonly _defaultBinding;
224
+ /**
225
+ * Keyed by the consumer, not its splat: a LOD-bundle environment swaps the
226
+ * splat that draws it as levels stream, and the override has to follow.
227
+ */
228
+ private readonly _overrides;
229
+ /** This frame's splat -> override binding, rebuilt by `_publish`. */
230
+ private readonly _overrideBySplat;
231
+ /** Splats this pass has attached a binding to, for detaching on destroy. */
232
+ private readonly _bound;
233
+ private readonly _viewProjection;
234
+ private readonly _params;
235
+ private readonly _composeParams;
236
+ private readonly _clearColor;
237
+ private readonly _size;
238
+ /**
239
+ * Build the pass for `scene`'s renderer.
240
+ *
241
+ * Throws when the renderer cannot render to half-float, which the lighting
242
+ * texture requires - lighting legitimately exceeds 1 and clamping it would
243
+ * flatten exactly the highlights relighting exists for - and when the scene
244
+ * renders with WebGPU but the `/webgpu` entry point has not been imported.
245
+ */
246
+ static create(scene: Scene, opts?: RelightPassOptions): RelightPass;
247
+ private constructor();
248
+ /**
249
+ * The composed lighting texture: `rgb` = full lighting, `a` = proxy
250
+ * coverage. `null` before the first frame has rendered. Exposed for debug
251
+ * overlays; the splats read it through their bindings.
252
+ */
253
+ get lightingTexture(): Texture | null;
254
+ /** `r` = shadow visibility, `g` = proxy coverage. See {@link lightingTexture}. */
255
+ get visibilityTexture(): Texture | null;
256
+ /** `[width, height]` of the lighting texture. */
257
+ get resolution(): [number, number];
258
+ /** Lighting-texture size as a fraction of the canvas. Reallocates. */
259
+ get resolutionScale(): number;
260
+ set resolutionScale(v: number);
261
+ /** See {@link RelightPassOptions.referenceLuminance}. Uniform-only. */
262
+ get referenceLuminance(): number;
263
+ set referenceLuminance(v: number);
264
+ /**
265
+ * Whether either tent runs at all. Reading it asks "is anything blurred";
266
+ * writing it sets both radii to 1 or 0. Uniform-only.
267
+ */
268
+ get blur(): boolean;
269
+ set blur(v: boolean);
270
+ /** Tent radius over the lighting, in proxy-target texels. Uniform-only. */
271
+ get blurRadius(): number;
272
+ set blurRadius(v: number);
273
+ /** Tent radius over the shadow-visibility channel. Uniform-only. */
274
+ get shadowBlurRadius(): number;
275
+ set shadowBlurRadius(v: number);
276
+ /** Whether the shadow-visibility channel is live (fixed at construction). */
277
+ get visibilityEnabled(): boolean;
278
+ /**
279
+ * Mirror the sampled row of the lighting texture.
280
+ *
281
+ * The backend's measured answer by default: `false` under WebGLRenderer,
282
+ * whose render-target rows run bottom-up exactly as `uv = ndc * 0.5 + 0.5`
283
+ * reads them, and whatever the WebGPU backend measured for WebGPURenderer.
284
+ * Kept settable because it is exactly the knob you want when a future
285
+ * three.js changes that behaviour: set {@link RelightParams.debug}, look
286
+ * for orange (coverage at the MIRRORED row), flip this and watch it turn
287
+ * grey.
288
+ */
289
+ get flipY(): boolean;
290
+ set flipY(v: boolean);
291
+ /** See {@link EnvironmentRefreshMode}. */
292
+ get environmentRefresh(): EnvironmentRefreshMode;
293
+ set environmentRefresh(v: EnvironmentRefreshMode);
294
+ /**
295
+ * Mark every binding changed, so a backend that caches on
296
+ * {@link SplatRelightBinding.version} recomputes. For what the pass cannot
297
+ * see itself.
298
+ */
299
+ invalidateEnvironments(): void;
300
+ /** Frames on which a published binding changed, since creation. A cost probe. */
301
+ get environmentRefreshFrames(): number;
302
+ /**
303
+ * Stop rendering the proxy. Consumers fall back to their baked colour on the
304
+ * same frame (the published `valid` flag goes to 0), so this is a true
305
+ * no-op, not a frozen last frame.
306
+ */
307
+ get enabled(): boolean;
308
+ set enabled(v: boolean);
309
+ /** Scene-wide relight defaults, applied to every splat without an override. */
310
+ setDefaults(params: RelightParams): void;
311
+ /** Read back the scene-wide defaults. */
312
+ getDefaults(): Required<RelightParams>;
313
+ /**
314
+ * Override the relight knobs for one {@link Splat} or {@link Environment}.
315
+ * Pass `null` to drop the override and fall back to {@link setDefaults}.
316
+ */
317
+ setConsumerParams(consumer: RelightConsumer, params: RelightParams | null): void;
318
+ /**
319
+ * Register a proxy mesh. It is moved onto {@link proxyLayerId} and given
320
+ * {@link proxyMaterial}, or {@link casterMaterial} when it only casts.
321
+ *
322
+ * When {@link RelightPassOptions.visibility} is on, a receiver also gets
323
+ * the unshadowed twin the visibility ratio is measured against: a child of
324
+ * the proxy sharing its geometry and, for a skinned proxy, its skeleton and
325
+ * bind matrices - so it needs no second skinning setup and cannot drift
326
+ * from the proxy it twins. Idempotent.
327
+ */
328
+ addProxy(mesh: Mesh, lightingReceiver?: boolean): void;
329
+ /** Drop a proxy registered with {@link addProxy}. No-op if unknown. */
330
+ removeProxy(mesh: Mesh): void;
331
+ /**
332
+ * Render the lighting for this frame and publish it. Called once a frame
333
+ * from the owner's `preRender`, after the proxies are posed.
334
+ */
335
+ render(): void;
336
+ /** Tear everything down. Safe to call twice. */
337
+ destroy(): void;
338
+ /** Idempotent, size-guarded allocator. No-op when the size already matches. */
339
+ private _ensureTargets;
340
+ private _releaseTargets;
341
+ /**
342
+ * Copy the main camera's view and projection onto the proxy camera, with
343
+ * the aspect taken from the TARGET rather than the canvas: the rounding of
344
+ * a scaled size can differ from the canvas ratio by a fraction of a
345
+ * percent, and the splat lookup uses this same matrix.
346
+ */
347
+ private _syncCamera;
348
+ private _renderProxies;
349
+ /**
350
+ * Point every live splat of this scene at its binding and write the frame's
351
+ * values into each binding once. Splats appear after the pass is built - LOD
352
+ * levels, variants, characters loaded later - so the scan runs every frame;
353
+ * a splat is only (re)attached when its binding changes, since that
354
+ * recompiles its shader.
355
+ */
356
+ private _publish;
357
+ /** Write one binding; `true` when anything in it changed. */
358
+ private _write;
359
+ }
360
+ /**
361
+ * The backend for the renderer `scene` draws with.
362
+ *
363
+ * @throws when the scene renders with WebGPU and the `/webgpu` entry point,
364
+ * which registers the TSL backend, has not been imported.
365
+ */
366
+ /** The relight backend for `scene`'s renderer. @internal */
367
+ export declare function relightBackendFor(scene: Scene): RelightBackend;
@@ -0,0 +1,2 @@
1
+ import type { Texture } from 'three';
2
+ export declare function getRelightPlaceholder(): Texture;
@@ -0,0 +1,4 @@
1
+ /** Full-screen triangle pair; `uv` comes from the plane, bottom-left origin like the targets. */
2
+ export declare const COMPOSE_VERTEX_GLSL = "\nout vec2 vUv0;\n\nvoid main(void) {\n vUv0 = uv;\n gl_Position = vec4(position.xy, 0.0, 1.0);\n}\n";
3
+ /** `RELIGHT_VISIBILITY` defined writes the visibility output, undefined the lighting. */
4
+ export declare const COMPOSE_FRAGMENT_GLSL = "\nin vec2 vUv0;\nlayout(location = 0) out highp vec4 outColor;\n\nuniform sampler2D uProxyLitTex;\nuniform sampler2D uProxyRawTex;\n// xy = one texel of the proxy target in uv; z = the lighting tent's radius in\n// texels, w = the shadow-visibility tent's. 0 on either is a single tap.\nuniform vec4 uComposeParams;\n// 1 when uProxyRawTex holds a real unshadowed render, 0 when it is a stand-in.\nuniform float uComposeHasRaw;\nuniform vec3 uComposeAmbient;\n\nvec4 tent(sampler2D src, vec2 uv, vec2 texel, float radius) {\n vec4 c = textureLod(src, uv, 0.0);\n if (radius <= 0.0) return c;\n vec2 t = texel * radius;\n vec4 sum = c * 4.0;\n sum += textureLod(src, uv + vec2(-t.x, -t.y), 0.0);\n sum += textureLod(src, uv + vec2( 0.0, -t.y), 0.0) * 2.0;\n sum += textureLod(src, uv + vec2( t.x, -t.y), 0.0);\n sum += textureLod(src, uv + vec2(-t.x, 0.0), 0.0) * 2.0;\n sum += textureLod(src, uv + vec2( t.x, 0.0), 0.0) * 2.0;\n sum += textureLod(src, uv + vec2(-t.x, t.y), 0.0);\n sum += textureLod(src, uv + vec2( 0.0, t.y), 0.0) * 2.0;\n sum += textureLod(src, uv + vec2( t.x, t.y), 0.0);\n return sum / 16.0;\n}\n\nvoid main(void) {\n vec2 t = uComposeParams.xy;\n\n vec4 lit = tent(uProxyLitTex, vUv0, t, uComposeParams.z);\n float cov = clamp(lit.a, 0.0, 1.0);\n // Un-premultiply. Below the threshold there is no proxy here at all, and\n // the lighting value is never read (the consumer gates on coverage).\n vec3 direct = cov > 1e-4 ? lit.rgb / cov : vec3(0.0);\n\n#ifndef RELIGHT_VISIBILITY\n outColor = vec4(direct + uComposeAmbient, cov);\n#else\n float visibility = 1.0;\n if (uComposeHasRaw > 0.5) {\n vec4 raw = tent(uProxyRawTex, vUv0, t, uComposeParams.w);\n float rawCov = clamp(raw.a, 0.0, 1.0);\n vec3 unshadowed = rawCov > 1e-4 ? raw.rgb / rawCov : vec3(0.0);\n // Luminance of the direct sums, exactly Unity's\n // weightTotal = Luminance(lightColor) * ndl * distanceAttenuation\n // weightLit = weightTotal * shadowAttenuation\n // summed over lights. The ratio therefore carries no N.L, no light\n // colour and no ambient of its own: a surface merely turned away from\n // every light has no light to lose and reports 1 (unshadowed) rather\n // than the darkness the relight path exists to express.\n float total = dot(unshadowed, vec3(0.2126, 0.7152, 0.0722));\n float reaching = dot(direct, vec3(0.2126, 0.7152, 0.0722));\n visibility = total > 1e-4 ? clamp(reaching / total, 0.0, 1.0) : 1.0;\n }\n outColor = vec4(visibility, cov, 0.0, 1.0);\n#endif\n}\n";
@@ -0,0 +1,26 @@
1
+ import { Vector3 } from 'three';
2
+ /**
3
+ * The key light's PlayCanvas depth bias, as the proxies take it when they
4
+ * receive its shadow. PlayCanvas offsets every caster's depth by
5
+ * `polygonOffset(f, f)` while it draws the shadow map (`f` from the light's
6
+ * `shadowBias`); the proxies, which are both the casters and the receivers
7
+ * that matter here, take the same offset at the receiving end instead:
8
+ * `f x one shadow texel x tan(angle to the light)`, toward the light. One per
9
+ * {@link SplatRelight}, written as it places its key light and read by that
10
+ * instance's proxy material (WebGL) or key light (WebGPU), so two instances
11
+ * never share a slope.
12
+ * @internal
13
+ */
14
+ export interface ProxyShadowBias {
15
+ /** Unit vector toward the key light, world space. */
16
+ readonly toLight: Vector3;
17
+ /** Polygon-offset slope factor times one shadow texel, in world units. 0: none. */
18
+ slope: number;
19
+ }
20
+ /** A zero bias, pointing straight up. @internal */
21
+ export declare function createProxyShadowBias(): ProxyShadowBias;
22
+ /**
23
+ * The receiver offset in GLSL: `relightSlopeOffset(worldNormal)` is the
24
+ * world-space shift toward the key light. @internal
25
+ */
26
+ export declare const PROXY_SHADOW_BIAS_GLSL = "\nuniform vec3 uRelightToLight;\nuniform float uRelightSlopeBias;\nvec3 relightSlopeOffset(vec3 n) {\n float c = dot(normalize(n), uRelightToLight);\n if (c <= 0.0 || uRelightSlopeBias == 0.0) return vec3(0.0);\n return uRelightToLight * (uRelightSlopeBias * sqrt(max(1.0 - c * c, 0.0)) / max(c, 1e-3));\n}\n";