@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,175 @@
1
+ export declare const SplatQuality: {
2
+ /**
3
+ * Alpha at which a splat's quad is allowed to end, so each one is sized to
4
+ * the radius its own opacity actually reaches instead of to the worst case.
5
+ * **The first knob to reach for on a weak GPU.**
6
+ *
7
+ * The fragment stage multiplies a gaussian falloff by the splat's opacity
8
+ * and discards anything below 1/255, so a quad drawn out to where that
9
+ * product is already below the cutoff spends fragments on a ring that
10
+ * cannot put ink on the screen. Raising the cutoff shrinks every quad. What
11
+ * it costs is a harder edge on each splat, which shows first on soft things
12
+ * - hair, fabric, anything semi-transparent.
13
+ *
14
+ * Takes effect on the next frame; nothing is reloaded and nothing is lost,
15
+ * so it is safe to drive from a frame-rate governor.
16
+ *
17
+ * | Value | What it is for |
18
+ * |---|---|
19
+ * | `1 / 255` | Exactly the behaviour before this knob existed. Changes nothing at all: below it a fragment is discarded anyway, so the quad it trims was drawing nothing. |
20
+ * | `8 / 255` | What the Unity build ships. The conservative end. |
21
+ * | `12 / 255` | **The default here.** |
22
+ * | `16 / 255` | **Low-end phones, and the floor.** Still 43.7 dB overall and 34.8 dB on the face, which the Unity build calls invisible at arm's length. |
23
+ * | above `16 / 255` | Not on this project. The Unity build measures a further -7% at 24/255, but the edges are visibly harder by then; a device that needs more should spend it on {@link SplatQuality.pruneRatio}, the renderer's pixel ratio, or a distance LOD, none of which harden every silhouette in the frame. |
24
+ *
25
+ * Measured on a Mali-G57 with three characters, against 8/255: 12/255 -7%,
26
+ * 16/255 -12%, 24/255 -19%. Measured here on an Apple GPU where fragments
27
+ * are the bottleneck, against 1/255: 8/255 -29%, 16/255 -42%, 24/255 -50%.
28
+ * Where the main thread is the bottleneck instead - the WebGL backend with
29
+ * animated characters - it is free but buys nothing; see the README's
30
+ * Tuning section for which case a scene is in.
31
+ */
32
+ quadAlphaCutoff: number;
33
+ /**
34
+ * Drop splats whose projected size falls below this radius in pixels, for
35
+ * every splat at once. `0` (the default) draws everything.
36
+ *
37
+ * The same test as the per-splat {@link Splat.minPixelSize}; the larger of
38
+ * the two wins, so a global floor cannot un-cull a splat an application
39
+ * already asked to cull. Removes distant crowd splats that cannot contribute
40
+ * more than a fraction of a pixel.
41
+ */
42
+ screenSizeCull: number;
43
+ /**
44
+ * Peak opacity a splat must reach to be kept when a character or scene is
45
+ * loaded. `0` keeps everything.
46
+ *
47
+ * A splat's alpha at its centre IS its opacity - the gaussian only falls
48
+ * off from there - so the faintest splats in a bundle are ones that paint
49
+ * almost nothing from any camera while still costing memory, a skinning
50
+ * pass, a sort slot and a quad. This removes them outright, which is what
51
+ * separates it from {@link SplatQuality.quadAlphaCutoff}: the cutoff
52
+ * shrinks a splat's quad and saves rasterisation alone, this saves
53
+ * everything, but it cannot half-remove one.
54
+ *
55
+ * **Applied during the decode of a CHARACTER bundle**, so it only affects
56
+ * what is loaded afterwards - set it before the first `load()`, and changing
57
+ * it later does nothing to characters already in the scene. It does not
58
+ * touch `.ply` scenes, matching the Unity build, which applies it in the
59
+ * skinned renderer and nowhere else: a scene's opacity distribution is a
60
+ * different thing, and 0.05 measured as 8.7% of a character against 41.8%
61
+ * of a 1M-splat room. {@link pruneSplats} is exported for an application
62
+ * that wants to make the trade on a scene of its own. It also changes
63
+ * {@link Splat.numSplats}, so an application that hands back a per-splat
64
+ * array ({@link Splat.setSplatGroups}) must size that array from
65
+ * `numSplats` after loading rather than from the file.
66
+ *
67
+ * | Value | What it is for |
68
+ * |---|---|
69
+ * | `0` | Keep every splat. The behaviour before this knob existed. |
70
+ * | `1 / 255` | Free in the strict sense: provably pixel-identical, because a splat under the fragment shader's own discard cannot produce a pixel. Worth about 2% of a character. |
71
+ * | `0.05` | **The default here, and what the Unity build ships.** Removes ~13% of a typical character for a difference of at most 11/255 on 1.3% of it - 58-62 dB, which does not read as a quality loss. |
72
+ * | above `0.05` | Untested. Prefer {@link SplatQuality.pruneRatio} to go further: it is measured, and it thins every region by the same share instead of taking the faintest splats wherever they happen to be - which is disproportionately the face. |
73
+ */
74
+ minOpacity: number;
75
+ /**
76
+ * Fraction of splats removed at load by voxel-local importance, on top of
77
+ * {@link SplatQuality.minOpacity}. `0` (the default) keeps everything, `0.5`
78
+ * drops the least-important half of every cell.
79
+ *
80
+ * Importance is opacity times a splat's two largest axes - the area it
81
+ * actually paints - ranked separately inside each spatial cell so a dense
82
+ * region loses the same share as a sparse one rather than being deleted
83
+ * wholesale. That per-cell quota is what keeps the face: a global ranking
84
+ * puts the many faint facial splats at the bottom and smears it. Measured on
85
+ * the Unity build's reference character at 0.5: 25,826 of 50,267 splats
86
+ * remain, the frame falls 24.5% on a Mali-G57, and the face holds 43.5 dB
87
+ * where a global rank gives 37.6.
88
+ *
89
+ * Applied during the decode of a character bundle, like
90
+ * {@link SplatQuality.minOpacity}, with the same scope and the same reason
91
+ * for being off by default.
92
+ */
93
+ pruneRatio: number;
94
+ /**
95
+ * Cell size, in metres, for {@link SplatQuality.pruneRatio}'s per-voxel
96
+ * quota.
97
+ *
98
+ * 4 cm gives ~19 splats per occupied cell on the Unity build's reference
99
+ * character - small enough that the face and the jacket are ranked apart,
100
+ * large enough that a cell has a population to rank. A tuning constant
101
+ * rather than a per-title knob, exposed because a character authored at a
102
+ * different scale needs a different one.
103
+ */
104
+ pruneVoxelSize: number;
105
+ /**
106
+ * Test each splat against the depth buffer, so opaque geometry hides the
107
+ * splats behind it. On by default.
108
+ *
109
+ * Unlike the Unity build, where turning this off was the single largest
110
+ * mobile saving, this is a correctness switch here and not a performance
111
+ * one: that build renders splats into an offscreen target and pays for the
112
+ * test by sampling a depth texture per fragment, where this package draws
113
+ * straight into the camera's target and gets the hardware depth test for
114
+ * free. Turning it off makes characters draw through walls and saves
115
+ * nothing. It is here because the behaviour is occasionally what an
116
+ * application wants - a character deliberately drawn over the scene.
117
+ */
118
+ depthOcclusion: boolean;
119
+ /**
120
+ * Collect {@link SplatQuality.timings}. Off by default.
121
+ *
122
+ * The CPU stages are timed with `performance.now()`, which is cheap but not
123
+ * free at a few calls per splat per frame, and a shipping application that
124
+ * never reads the numbers should not pay for them.
125
+ */
126
+ passTimings: boolean;
127
+ /**
128
+ * Per-stage cost of the last frame in which {@link SplatQuality.passTimings}
129
+ * was on, in milliseconds, summed over every splat that ran that stage.
130
+ *
131
+ * These are main-thread times, which is the measurement that matters for
132
+ * this package: under `WebGLRenderer` the per-character CPU cost - skinning
133
+ * every centre to feed the sort, then the sort - is what limits how many
134
+ * characters a scene can carry, and neither stage exists on the GPU
135
+ * timeline. `skin` and `sort` are zero under `WebGPURenderer`, where both
136
+ * happen in compute; `splatsDrawn` and `splatsTotal` are meaningful on both,
137
+ * and differ when {@link SplatQuality.screenSizeCull} or a count LOD is
138
+ * reducing what is submitted.
139
+ *
140
+ * These describe the most recent pass in which any splat drew, so read them
141
+ * after your render call. A pass that drew no splats leaves the previous
142
+ * numbers in place rather than zeroing them - a zero and "nothing happened"
143
+ * would otherwise read the same, which is the mistake the Unity build's
144
+ * equivalent made and spent a long time chasing.
145
+ */
146
+ timings: {
147
+ /** CPU skinning of splat centres, i.e. `Splat.ensureCenters`. */
148
+ skin: number;
149
+ /** The depth sort, where it runs on the main thread. */
150
+ sort: number;
151
+ /** Uniform and buffer updates in `beforeRender`, excluding skin and sort. */
152
+ prepare: number;
153
+ /** Splat instances submitted to the GPU this frame. */
154
+ splatsDrawn: number;
155
+ /** Splat instances those draws could have covered at full detail. */
156
+ splatsTotal: number;
157
+ };
158
+ /** Restore every knob to its default. Call when tearing the engine down. */
159
+ resetStatics(): void;
160
+ };
161
+ /** The effective sub-pixel cull for one splat: its own floor or the global one. */
162
+ export declare function effectiveMinPixelSize(splatMinPixelSize: number): number;
163
+ /**
164
+ * Add a CPU skinning measurement for the frame now being prepared.
165
+ * @internal
166
+ */
167
+ export declare function addSkinTime(ms: number): void;
168
+ /**
169
+ * Open this pass's timing accumulation, clearing it when `source` - the splat
170
+ * reporting - has already contributed, which means a new pass has begun.
171
+ * Called by every backend before it adds to {@link SplatQuality.timings}.
172
+ *
173
+ * @internal
174
+ */
175
+ export declare function beginFrameTimings(source: object): void;
@@ -0,0 +1,39 @@
1
+ import { Matrix4, Vector3, Vector4 } from 'three';
2
+ import type { Texture } from 'three';
3
+ /**
4
+ * What a relight writes for one splat: the screen-space lighting it rendered
5
+ * for the splat's proxy, and how to sample it. The splat shader projects each
6
+ * splat centre through {@link viewProjection} into {@link texture} and
7
+ * multiplies its colour by the lighting found there.
8
+ *
9
+ * The {@link SplatRelight} system owns and updates these; a splat only reads
10
+ * them. Every field is bound by reference, so a relight updates a binding in
11
+ * place and the next frame picks it up.
12
+ *
13
+ * Mirrors the PlayCanvas build's `uRelight*` work-buffer uniforms.
14
+ *
15
+ * @internal
16
+ */
17
+ export declare class SplatRelightBinding {
18
+ /** rgb = lighting, a = proxy coverage. */
19
+ texture: Texture | null;
20
+ /** r = shadow visibility, g = coverage. */
21
+ shadowTexture: Texture | null;
22
+ /** The view-projection the textures were rendered with. */
23
+ readonly viewProjection: Matrix4;
24
+ /** xy = 1 / texture size, z = 1 / reference luminance, w = 1 when the textures are valid. */
25
+ readonly params: Vector4;
26
+ /** 0..1: how much of the lighting is applied. */
27
+ strength: number;
28
+ readonly tint: Vector3;
29
+ /** Lighting floor, so a splat in full shade keeps some of its colour. */
30
+ ambient: number;
31
+ /** 0..1: how much of the shadow is applied. */
32
+ shadowStrength: number;
33
+ /** 1 when the textures' rows run top-down. */
34
+ flipY: number;
35
+ /** 0 off, 1 lighting debug colours, 2 shadow visibility. */
36
+ debug: number;
37
+ /** Bumped by the relight whenever a field changes, so a backend can skip work. */
38
+ version: number;
39
+ }
@@ -0,0 +1,43 @@
1
+ /**
2
+ * The reveal's per-splat bake: a continuous feet-to-head coordinate along the
3
+ * skeleton, so the front of {@link Splat.setReveal} walks up the body rather
4
+ * than sweeping a flat plane. Pure, so it runs without a GPU.
5
+ */
6
+ /** Skeleton distances shared by every splat of one character. */
7
+ export interface RevealSkeleton {
8
+ /** Bind-pose bone positions, `numBones * 3`. */
9
+ pos: Float32Array;
10
+ /** Distance from the nearest foot; `-1` = off the body graph. */
11
+ chain: Float32Array;
12
+ /** Parents, with deformation helpers flattened out. */
13
+ parents: Int32Array;
14
+ }
15
+ /**
16
+ * Distances along the body graph, measured from the nearest foot. Pelvis is
17
+ * `pelvisHint` when given, else from the rig's bone names; failing both, the
18
+ * bone nearest `centre`.
19
+ */
20
+ export declare function buildRevealSkeleton(pos: Float32Array, parents: ArrayLike<number>, names: readonly string[], centre: {
21
+ x: number;
22
+ y: number;
23
+ z: number;
24
+ }, pelvisHint?: number): RevealSkeleton | null;
25
+ /** A splat cloud's rest positions and its `k` bone influences per splat. */
26
+ export interface RevealSplats {
27
+ x: ArrayLike<number>;
28
+ y: ArrayLike<number>;
29
+ z: ArrayLike<number>;
30
+ indices: ArrayLike<number>;
31
+ weights: ArrayLike<number>;
32
+ numSplats: number;
33
+ }
34
+ /**
35
+ * Write each splat's normalized distance, 0 at the feet and 1 at the far end
36
+ * of the body, into `out`: its position projected onto the nearest bone
37
+ * segment of its influences, interpolated along {@link RevealSkeleton.chain}.
38
+ * Returns false, leaving `out` untouched, when the skeleton has no length.
39
+ *
40
+ * @param boneRemap - Splat bone index to skeleton bone, `-1` when unmapped,
41
+ * or `null` when they already agree.
42
+ */
43
+ export declare function bakeRevealDistances(out: Float32Array, splats: RevealSplats, skeleton: RevealSkeleton, boneRemap: ArrayLike<number> | null): boolean;
@@ -0,0 +1,64 @@
1
+ /**
2
+ * How a character reveal looks: a bright band that walks the skeleton from
3
+ * feet to head, with sparse sketch dots just ahead of it. Distances are
4
+ * fractions of that feet-to-head path. Every field is optional; unset fields
5
+ * keep their current value. See {@link Character.setReveal}.
6
+ *
7
+ * @group Splats
8
+ */
9
+ export interface RevealLook {
10
+ /** Width of the bright band behind the front. */
11
+ bandWidth?: number;
12
+ /** Share of the band held at full brightness before it fades, 0-1. */
13
+ bandHold?: number;
14
+ /** Longest a splat may stretch inside the band, in multiples of its shortest axis. */
15
+ bandMaxStretch?: number;
16
+ /** How far ahead of the front the sketch dots start. */
17
+ sketchLead?: number;
18
+ /** Share of splats drawn as sketch dots, 0-1. */
19
+ sketchDensity?: number;
20
+ /** Size of a sketch dot relative to its splat. */
21
+ sketchScale?: number;
22
+ /** Colour the band leans toward, 0-1 per channel. */
23
+ tint?: {
24
+ r: number;
25
+ g: number;
26
+ b: number;
27
+ };
28
+ /** Luminance below which the band is lifted toward {@link tint}. */
29
+ tintFloor?: number;
30
+ }
31
+ /** The engine's default reveal look. */
32
+ export declare const DEFAULT_REVEAL_LOOK: Readonly<Required<RevealLook>>;
33
+ /**
34
+ * The default look for an ENVIRONMENT reveal, where the sweep is radial
35
+ * distance from the capture point rather than a path up a body. Distances are
36
+ * fractions of the room's radius either way, so these are the same numbers
37
+ * read against a different subject - and the subject is what moves them.
38
+ *
39
+ * A body's feet-to-head coordinate is a line: a narrow band shows a thin ring
40
+ * of it, and a sweep up it is legible. A room's radius is a SHELL, and a
41
+ * Flow2D capture keeps most of its splats in the one shell that is its walls,
42
+ * so the character's 0.07 band crosses nearly the whole room in a single
43
+ * instant - a flashbulb, not an assembly. The band is wider here and holds
44
+ * less of its width at full brightness, which turns that slab into a front
45
+ * with a falloff behind it; a wide band at the character's 0.6 hold would be
46
+ * a wall of white across the entire frame instead.
47
+ *
48
+ * The dots thin out for the same reason. A character is a few hundred
49
+ * thousand splats in the middle of the frame, where 15% of them reads as a
50
+ * sketch; a scene is millions of them filling it edge to edge, where 15%
51
+ * reads as fog. They also lead by more than the band is wide, so the shape of
52
+ * the room is legible just before it lands.
53
+ *
54
+ * The colour is deliberately the character's, unchanged: the two reveals are
55
+ * one effect seen on two subjects, and a scene that assembled in a different
56
+ * hue would say they were not.
57
+ */
58
+ export declare const DEFAULT_ENV_REVEAL_LOOK: Readonly<Required<RevealLook>>;
59
+ /**
60
+ * Write the set fields of `look` into the shader's three uniforms:
61
+ * `band` = (width, hold, max stretch), `sketch` = (lead, density, dot scale),
62
+ * `tint` = (r, g, b, luminance floor).
63
+ */
64
+ export declare function packRevealLook(look: RevealLook, band: Float32Array, sketch: Float32Array, tint: Float32Array): void;
@@ -47,6 +47,7 @@ export declare class SplatMesh extends Mesh {
47
47
  syncBounds(): void;
48
48
  syncBoneData(): void;
49
49
  syncVariantGroups(): void;
50
+ syncRelight(): void;
50
51
  onBeforeRender(renderer: unknown, _scene: unknown, camera: Camera): void;
51
52
  /**
52
53
  * A second mesh drawing the same splat data, at the same transform. The
@@ -3,7 +3,11 @@ import type { Frustum } from 'three';
3
3
  import type { SplatEngine } from '../engine';
4
4
  import type { Mat4 } from '../math';
5
5
  import type { SplatWeights } from '../types';
6
+ import type { SplatColorModifier } from './color-modifier';
6
7
  import type { PackedSplats } from './packed-splats';
8
+ import type { SplatRelightBinding } from './relight-binding';
9
+ import type { RevealSkeleton } from './reveal-bake';
10
+ import type { RevealLook } from './reveal-look';
7
11
  import { SplatMesh } from './splat-mesh';
8
12
  import { TransformPalette } from './transform-palette';
9
13
  /** What a {@link Splat} is built from: packed gaussians, plus skinning data for characters. */
@@ -61,6 +65,21 @@ export declare class Splat {
61
65
  readonly tint: Vector4;
62
66
  /** x contrast, y saturation. Shared with the material by reference. */
63
67
  readonly grade: Vector2;
68
+ /**
69
+ * x opacity, y reveal amount, z reveal inverse (0/1), w cut amount. Shared
70
+ * with the material by reference. `(1, 1, 0, 0)` changes nothing.
71
+ */
72
+ readonly effects: Vector4;
73
+ /** Reveal look: band (width, hold, max stretch), sketch (lead, density, dot scale), tint (rgb, luminance floor). */
74
+ readonly revealBand: Vector4;
75
+ readonly revealSketch: Vector4;
76
+ readonly revealTint: Vector4;
77
+ /** Per-splat feet-to-head distance for the reveal. Skinned splats only, after {@link setReveal} opts in. */
78
+ revealDistanceTexture?: DataTexture;
79
+ /** Per-piece cut data, `numGroups x 1` each: offset + scale, pivot, axis + angle. See {@link setCutGroups}. */
80
+ groupOffsetsTexture?: DataTexture;
81
+ groupPivotsTexture?: DataTexture;
82
+ groupRotsTexture?: DataTexture;
64
83
  linkedArmature: any;
65
84
  /** Skinning influences normalised to exactly four slots per splat. */
66
85
  splatWeights?: SplatWeights;
@@ -83,11 +102,22 @@ export declare class Splat {
83
102
  readonly localBounds: Box3;
84
103
  /** Discard splats smaller than this many pixels on screen. `0` draws everything. */
85
104
  minPixelSize: number;
105
+ private _activeSplatCount;
106
+ private _importanceOrder;
107
+ /** `_importanceOrder` inverted: each splat's place in it. @internal */
108
+ private _importanceRank;
86
109
  private readonly _mesh;
87
110
  private _cpuInfluences;
88
111
  private _pendingBoneTransforms;
89
112
  private _flatBones;
90
113
  private _variantMaskEnabled;
114
+ private _cutEnabled;
115
+ private _revealEnabled;
116
+ private _revealBaked;
117
+ private _colorModifier;
118
+ private _relight;
119
+ private _boneMapFirstIdx;
120
+ private _boneMapRemap;
91
121
  private _nonRigidCov;
92
122
  private _antiAlias;
93
123
  private _destroyed;
@@ -103,8 +133,65 @@ export declare class Splat {
103
133
  cloneStatic(engine: SplatEngine, asyncSort: boolean): Splat;
104
134
  /** Top-4 influences per splat, zero-padded. The shader and the CPU path both assume four. */
105
135
  private _normalizeWeights;
136
+ /**
137
+ * How many splats are skinned, sorted and drawn this frame: the whole set,
138
+ * or the first `n` of {@link Splat.importanceOrder} after
139
+ * {@link Splat.setCountLod}.
140
+ */
141
+ get activeSplatCount(): number;
142
+ /** Whether a count LOD is currently reducing this splat. */
143
+ get countLodActive(): boolean;
144
+ /**
145
+ * Process only the `n` most important splats this frame, or the whole set
146
+ * with `null`.
147
+ *
148
+ * The dynamic counterpart of {@link SplatQuality.pruneRatio}: the prune
149
+ * decides once, at load, that some splats are not worth carrying at all,
150
+ * while this decides per frame how many of them are worth the work right
151
+ * now - which is the trade a character makes as it walks away from the
152
+ * camera. Nothing is freed, so it reverses the moment `n` goes back up.
153
+ *
154
+ * Which splats the first `n` are is {@link Splat.importanceOrder}'s answer:
155
+ * the strongest splat of every 4 cm cell, then the second of every cell, and
156
+ * so on, so the character thins evenly rather than losing a region.
157
+ *
158
+ * `WebGLRenderer` only, where it is worth the most: that backend skins every
159
+ * splat centre on the CPU each frame to feed its sort, and this cuts that
160
+ * pass, the sort and the draw together. Under `WebGPURenderer` all of that
161
+ * already happens in compute, and the call is accepted and ignored rather
162
+ * than silently changing which splats a GPU sort can see.
163
+ *
164
+ * {@link Character.setSplatCountLod} drives this from camera distance; call
165
+ * it directly for a policy of your own.
166
+ */
167
+ setCountLod(n: number | null): void;
168
+ /**
169
+ * Build {@link Splat.importanceOrder} now, if it does not exist yet.
170
+ *
171
+ * One pass over the splats plus a small sort inside each 4 cm cell - single
172
+ * digit milliseconds for a character, but milliseconds that would otherwise
173
+ * land on the frame where the LOD first engages, which is a frame where the
174
+ * camera is already moving. {@link Character.setSplatCountLod} calls this
175
+ * when the LOD is configured, so the cost lands there instead.
176
+ */
177
+ prepareCountLod(): void;
178
+ /**
179
+ * Each splat's place in {@link Splat.importanceOrder}, which is how the
180
+ * per-frame passes test membership of the active prefix. `null` until
181
+ * {@link Splat.prepareCountLod}.
182
+ * @internal
183
+ */
184
+ get importanceRank(): Uint32Array | null;
185
+ /**
186
+ * Splat indices ordered by importance for {@link Splat.setCountLod}. `null`
187
+ * until {@link Splat.prepareCountLod} or a count LOD has asked for one.
188
+ */
189
+ get importanceOrder(): Uint32Array | null;
106
190
  /** Re-upload the bone index/weight textures after editing their data arrays. */
107
191
  markBoneTexturesDirty(): void;
192
+ /** Keep CPU-skinned centres (sorting and ground probes) on the same bone
193
+ * mapping as the GPU shader. Called once when an armature binds this splat. */
194
+ syncMappedCpuInfluences(firstPaletteIdx: number): void;
108
195
  get variantMaskEnabled(): boolean;
109
196
  get nonRigidCovariance(): boolean;
110
197
  /**
@@ -133,9 +220,142 @@ export declare class Splat {
133
220
  }): void;
134
221
  /** Per-splat colour grade. `(1, 1)` is a true no-op. */
135
222
  setGrade(contrast: number, saturation: number): void;
223
+ /**
224
+ * Like {@link setTint}, but multiplies: the splat colour times `color`, by
225
+ * `strength` (0..1). Darkens or browns while keeping the splat's own
226
+ * variation (cooking, scorching). `setTint` goes back to the mix.
227
+ */
228
+ setTintMultiply(strength: number, color?: {
229
+ r: number;
230
+ g: number;
231
+ b: number;
232
+ }): void;
233
+ /** Multiply every splat's alpha by `opacity` (0..1); 1, the default, leaves it. */
234
+ setOpacity(opacity: number): void;
235
+ /** The value last given to {@link setOpacity}. */
236
+ get opacity(): number;
237
+ /**
238
+ * Reveal amount in [0, 1]. At 1 (the default) the splat renders unchanged.
239
+ * Below 1 a bright front walks from feet to head, with sparse dots just
240
+ * ahead of it. Zero is invisible. `inverse` keeps the area ahead of the
241
+ * front instead, for outgoing transitions.
242
+ *
243
+ * The first call below 1 (or with `inverse`) opts the splat in: it bakes
244
+ * the per-splat distances through the linked {@link Armature} and rebuilds
245
+ * the shader. Call {@link Armature.prepareReveal} after loading to pay that
246
+ * up front. A splat that is never revealed pays nothing.
247
+ */
248
+ setReveal(amount: number, inverse?: boolean): void;
249
+ /**
250
+ * Change how the reveal looks. Unset fields keep their current value; the
251
+ * starting look is {@link DEFAULT_REVEAL_LOOK}.
252
+ */
253
+ setRevealLook(look: RevealLook): void;
254
+ /** Whether the reveal has been opted into - see {@link setReveal}. */
255
+ get revealEnabled(): boolean;
256
+ /** Whether {@link bakeReveal} has run for this splat. */
257
+ get revealBaked(): boolean;
258
+ private _enableReveal;
259
+ /**
260
+ * Bake the per-splat reveal distances against `skeleton`, opting the splat
261
+ * into the reveal. Called by {@link Armature.prepareReveal}.
262
+ *
263
+ * @param boneRemap - Splat bone index to armature bone, `-1` when unmapped,
264
+ * or `null` when the splat's bones are the armature's.
265
+ */
266
+ bakeReveal(skeleton: RevealSkeleton, boneRemap: ArrayLike<number> | null): void;
267
+ /** Whether {@link setCutGroups} has opted this splat in. */
268
+ get cutEnabled(): boolean;
269
+ /**
270
+ * Opt this splat into a "cut": its splats split into pieces that slide,
271
+ * tumble and scale apart. `groupIds` tags each splat with a piece; each
272
+ * piece gets a model-space `offset`, and optionally a `pivot` and a
273
+ * `rotation` (it tumbles rigidly about its pivot) and a uniform `scale`
274
+ * about the pivot. Starts fully cut ({@link setCut} 1); animate with
275
+ * `setCut`. Uses the {@link setSplatGroups} group ids.
276
+ *
277
+ * @param groupIds - per-splat piece, length {@link numSplats}.
278
+ * @param offsets - `numGroups x 3` model-space offsets.
279
+ * @param numGroups - the number of pieces.
280
+ * @param pivots - optional `numGroups x 3` pivots (default the origin).
281
+ * @param rotations - optional `numGroups x 4`: unit axis xyz, angle (rad).
282
+ * @param scales - optional `numGroups` uniform scales (default 1).
283
+ */
284
+ setCutGroups(groupIds: Uint8Array, offsets: Float32Array, numGroups: number, pivots?: Float32Array, rotations?: Float32Array, scales?: Float32Array): void;
285
+ /**
286
+ * Rewrite the pieces' offsets, pivots, rotations and scales without a
287
+ * shader rebuild, e.g. to dice finer on each chop, then show them fully
288
+ * cut. No-op before {@link setCutGroups}, or with more groups than it
289
+ * allocated.
290
+ */
291
+ setCutOffsets(offsets: Float32Array, numGroups: number, pivots?: Float32Array, rotations?: Float32Array, scales?: Float32Array): void;
292
+ /** How far apart the pieces are: 0 whole, 1 fully cut. No-op before {@link setCutGroups}. */
293
+ setCut(amount: number): void;
294
+ private _uploadCutData;
295
+ /** Set {@link localBounds} to the uncut bounds grown by the cut's reach, once. @internal */
296
+ private _padForCut;
297
+ private _cutPad;
298
+ private readonly _uncutBounds;
299
+ /** The hook set by {@link setColorModifier}, or `null`. */
300
+ get colorModifier(): SplatColorModifier | null;
301
+ /**
302
+ * Run a colour hook of the game's own on every splat, after the engine's
303
+ * colour work - see {@link SplatColorModifier}. `null` removes it. Each
304
+ * call rebuilds the shader; change the hook's uniforms to animate it.
305
+ */
306
+ setColorModifier(modifier: SplatColorModifier | null): void;
307
+ /** The relight writing into this splat, or `null`. @internal */
308
+ get relightBinding(): SplatRelightBinding | null;
309
+ /**
310
+ * Attach the per-splat output of a {@link SplatRelight}, or detach it with
311
+ * `null`. Rebuilds the shader when the relight turns on or off.
312
+ * @internal
313
+ */
314
+ setRelightBinding(binding: SplatRelightBinding | null): void;
315
+ /**
316
+ * Put the splat on exactly these three.js layers (0..31), for cameras that
317
+ * render a subset of the scene. `[0]` is the default.
318
+ */
319
+ setLayers(layerIds: number[]): void;
320
+ /**
321
+ * Record the palette base and source->target remap the armature chose when
322
+ * it bound this splat, so a later {@link reuploadBoneWeights} writes
323
+ * palette slots, not raw rig indices.
324
+ */
325
+ rememberBoneMapping(firstIdx: number, _numBones: number, remap: Int32Array | null): void;
326
+ /**
327
+ * `true` once this splat's bone weights are its own to edit. Splats built
328
+ * from shared decoded data (clones, overlays) share
329
+ * {@link Splat.splatWeights} until {@link privatizeBoneWeights}.
330
+ */
331
+ get boneWeightsArePrivate(): boolean;
332
+ private _weightsPrivate;
333
+ /**
334
+ * Give this splat its own copy of {@link Splat.splatWeights}, so editing
335
+ * them (a ragdoll detaching a limb, hit-based weight pruning) and calling
336
+ * {@link reuploadBoneWeights} leaves every other splat alone. Idempotent.
337
+ */
338
+ privatizeBoneWeights(): void;
339
+ /**
340
+ * Upload the current {@link Splat.splatWeights} to the GPU after editing
341
+ * them, through the palette mapping the armature chose. Call
342
+ * {@link privatizeBoneWeights} first.
343
+ */
344
+ reuploadBoneWeights(): void;
345
+ /**
346
+ * Splat centres (splat-local) in the latest pose. Under WebGL they are
347
+ * kept current anyway; under WebGPU this skins them on the CPU on demand,
348
+ * for picking or ground probes.
349
+ */
350
+ posedCenters(): Float32Array;
136
351
  /**
137
352
  * Assign each splat to a group and enable per-group visibility. All groups
138
353
  * start visible; toggle them with {@link Splat.setVariantMask}.
354
+ *
355
+ * `groupIds` is indexed by splat, so it has to be built against
356
+ * {@link Splat.numSplats} as loaded - which {@link SplatQuality.minOpacity}
357
+ * makes smaller than the count in the file. An array authored offline
358
+ * against the file cannot simply be shortened: see the error this throws.
139
359
  */
140
360
  setSplatGroups(groupIds: Uint8Array, numGroups: number): void;
141
361
  /** Per-group visibility, one entry per group: `>= 0.5` shows the group. */
@@ -1,2 +1,6 @@
1
- export declare const SPLAT_VERTEX_GLSL = "\nprecision highp float;\nprecision highp int;\nprecision highp usampler2D;\n\n// Quad corner in [-1, 1].\nin vec3 position;\n// Index of the splat this instance draws; instances arrive back-to-front.\nin uint splatOrder;\n\nuniform mat4 modelMatrix;\nuniform mat4 viewMatrix;\nuniform mat4 projectionMatrix;\n\nuniform highp usampler2D tTransformA;\nuniform highp sampler2D tTransformB;\nuniform highp sampler2D tColor;\nuniform int uTexWidth;\n\n// Drawing-buffer size in pixels.\nuniform vec2 uViewport;\nuniform float uMinPixelSize;\n// World rotation (xyzw) and scale of the splat object.\nuniform vec4 uModelRotation;\nuniform vec3 uModelScale;\n// rgb tint colour, a tint amount.\nuniform vec4 uTint;\n// x contrast, y saturation.\nuniform vec2 uGrade;\n// 1 when the render target expects linear colour, 0 when it is display-referred.\nuniform float uOutputLinear;\n\nout mediump vec2 gaussianUV;\nout mediump vec4 gaussianColor;\n\n\nuniform vec3 uSunColor;\nuniform float uSunIntensity;\nuniform vec3 uAmbientColor;\nuniform int uPointLightCount;\nuniform highp sampler2D uPointLightTex;\n\n// Baked splat colour is multiplied by this. With no lights it is exactly 1.\nvec3 computeLitFactor(vec3 worldCenter) {\n vec3 lit = uAmbientColor + uSunColor * uSunIntensity;\n for (int i = 0; i < uPointLightCount; i++) {\n vec4 posRange = texelFetch(uPointLightTex, ivec2(i, 0), 0);\n vec4 colorInt = texelFetch(uPointLightTex, ivec2(i, 1), 0);\n vec3 toLight = posRange.xyz - worldCenter;\n float dist = length(toLight);\n float range = posRange.w;\n if (dist >= range) continue;\n float t = dist / range;\n float atten = 1.0 - t * t;\n atten = atten * atten;\n lit += colorInt.rgb * colorInt.w * atten;\n }\n return lit;\n}\n\n\nuniform highp sampler2D transformPalette;\n\n#ifdef USE_BONE_BLENDING\nuniform highp sampler2D boneIndices;\nuniform highp sampler2D boneWeights;\n#endif\n\n#ifdef USE_VARIANT_MASK\nuniform highp sampler2D splatGroupIds;\nuniform highp sampler2D splatVariantMask;\n\nbool isSplatHiddenByVariantMask(ivec2 splatUV) {\n float gidF = texelFetch(splatGroupIds, splatUV, 0).r;\n int gid = int(gidF + 0.5);\n float bit = texelFetch(splatVariantMask, ivec2(gid, 0), 0).r;\n return bit < 0.5;\n}\n#endif\n\nbool isReasonablePaletteTransform(mat4 t) {\n mat3 lin = mat3(t);\n vec3 s = vec3(length(lin[0]), length(lin[1]), length(lin[2]));\n // Reject only when EVERY column is near-zero (a truly empty palette slot).\n // Linear-blend skinning of two very different bone rotations produces a\n // candy-wrapper matrix with one short column; that is still a valid\n // mid-rotation transform. Requiring all columns to pass would collapse\n // joint-spanning splats (notably the neck) back to the bind pose.\n return any(greaterThan(s, vec3(1e-4)));\n}\n\nmat4 readTransformFromPalette(uint paletteIndex) {\n if (paletteIndex == 0u) {\n return mat4(1.0);\n }\n\n int u = int(paletteIndex % 512u) * 3;\n int v = int(paletteIndex / 512u);\n\n mat4 t;\n t[0] = texelFetch(transformPalette, ivec2(u, v), 0);\n t[1] = texelFetch(transformPalette, ivec2(u + 1, v), 0);\n t[2] = texelFetch(transformPalette, ivec2(u + 2, v), 0);\n t[3] = vec4(0.0, 0.0, 0.0, 1.0);\n\n mat4 result = transpose(t);\n if (!isReasonablePaletteTransform(result)) {\n return mat4(1.0);\n }\n return result;\n}\n\nmat4 getSplatPaletteTransform(ivec2 splatUV) {\n #ifdef USE_BONE_BLENDING\n vec4 boneIdxVec = texelFetch(boneIndices, splatUV, 0);\n vec4 boneWeightVec = texelFetch(boneWeights, splatUV, 0);\n float totalWeight = dot(boneWeightVec, vec4(1.0));\n if (totalWeight > 0.001) {\n mat4 blended = mat4(0.0);\n for (int i = 0; i < 4; i++) {\n float w = boneWeightVec[i];\n if (w > 0.001) {\n uint idx = uint(boneIdxVec[i] + 0.5);\n blended += readTransformFromPalette(idx) * w;\n }\n }\n mat4 result = blended / totalWeight;\n if (isReasonablePaletteTransform(result)) {\n return result;\n }\n }\n #endif\n\n return mat4(1.0);\n}\n\nvec4 mat3ToQuatXYZW(mat3 R) {\n vec4 q;\n float trace = R[0][0] + R[1][1] + R[2][2];\n if (trace > 0.0) {\n float s = sqrt(trace + 1.0) * 2.0;\n q.w = 0.25 * s;\n q.x = (R[1][2] - R[2][1]) / s;\n q.y = (R[2][0] - R[0][2]) / s;\n q.z = (R[0][1] - R[1][0]) / s;\n } else if (R[0][0] > R[1][1] && R[0][0] > R[2][2]) {\n float s = sqrt(1.0 + R[0][0] - R[1][1] - R[2][2]) * 2.0;\n q.w = (R[1][2] - R[2][1]) / s;\n q.x = 0.25 * s;\n q.y = (R[1][0] + R[0][1]) / s;\n q.z = (R[2][0] + R[0][2]) / s;\n } else if (R[1][1] > R[2][2]) {\n float s = sqrt(1.0 + R[1][1] - R[0][0] - R[2][2]) * 2.0;\n q.w = (R[2][0] - R[0][2]) / s;\n q.x = (R[1][0] + R[0][1]) / s;\n q.y = 0.25 * s;\n q.z = (R[2][1] + R[1][2]) / s;\n } else {\n float s = sqrt(1.0 + R[2][2] - R[0][0] - R[1][1]) * 2.0;\n q.w = (R[0][1] - R[1][0]) / s;\n q.x = (R[2][0] + R[0][2]) / s;\n q.y = (R[2][1] + R[1][2]) / s;\n q.z = 0.25 * s;\n }\n return q;\n}\n\n\nconst vec4 discardVec = vec4(0.0, 0.0, 2.0, 1.0);\n\nmat3 quatToMat3(vec4 R) {\n vec4 R2 = R + R;\n float X = R2.x * R.w;\n vec4 Y = R2.y * R;\n vec4 Z = R2.z * R;\n float W = R2.w * R.w;\n return mat3(\n 1.0 - Z.z - W, Y.z + X, Y.w - Z.x,\n Y.z - X, 1.0 - Y.y - W, Z.w + Y.x,\n Y.w + Z.x, Z.w - Y.x, 1.0 - Y.y - Z.z\n );\n}\n\nvec4 quatMul(vec4 a, vec4 b) {\n return vec4(\n a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,\n a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,\n a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,\n a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z\n );\n}\n\nvoid computeCovariance(vec4 rotation, vec3 scale, out vec3 covA, out vec3 covB) {\n mat3 rot = quatToMat3(rotation);\n mat3 M = transpose(mat3(\n scale.x * rot[0],\n scale.y * rot[1],\n scale.z * rot[2]\n ));\n covA = vec3(dot(M[0], M[0]), dot(M[0], M[1]), dot(M[0], M[2]));\n covB = vec3(dot(M[1], M[1]), dot(M[1], M[2]), dot(M[2], M[2]));\n}\n\nvec3 sRGBToLinear(vec3 c) {\n return mix(\n pow(c * 0.9478672986 + vec3(0.0521327014), vec3(2.4)),\n c * 0.0773993808,\n vec3(lessThanEqual(c, vec3(0.04045)))\n );\n}\n\nvoid main(void) {\n ivec2 splatUV = ivec2(int(splatOrder % uint(uTexWidth)), int(splatOrder / uint(uTexWidth)));\n uvec4 tA = texelFetch(tTransformA, splatUV, 0);\n vec4 tB = texelFetch(tTransformB, splatUV, 0);\n\n vec3 modelCenter = uintBitsToFloat(tA.xyz);\n vec3 packedRot = vec3(unpackHalf2x16(tA.w), tB.w);\n // xyzw, with w recovered: quaternions are stored on the w >= 0 hemisphere.\n vec4 srcRotation = vec4(packedRot, sqrt(max(0.0, 1.0 - dot(packedRot, packedRot))));\n vec3 srcScale = tB.xyz;\n\n // ---- Skin, then lift to world space --------------------------------\n mat4 palette = getSplatPaletteTransform(splatUV);\n vec3 modelDeformed = (palette * vec4(modelCenter, 1.0)).xyz;\n vec3 worldCenter = (modelMatrix * vec4(modelDeformed, 1.0)).xyz;\n\n vec4 worldRotation = quatMul(uModelRotation, srcRotation);\n if (worldRotation.w < 0.0) worldRotation = -worldRotation;\n vec3 worldScale = uModelScale * srcScale;\n\n #ifdef USE_BONE_BLENDING\n {\n // The full world-space skinning rotation comes from modelMatrix * palette;\n // the palette's own scale is deliberately dropped (rigid skinning).\n mat3 lin = mat3(modelMatrix * palette);\n vec3 s = vec3(length(lin[0]), length(lin[1]), length(lin[2]));\n if (s.x > 1e-5 && s.y > 1e-5 && s.z > 1e-5) {\n mat3 rot = mat3(lin[0] / s.x, lin[1] / s.y, lin[2] / s.z);\n vec4 composed = normalize(quatMul(mat3ToQuatXYZW(rot), srcRotation));\n if (composed.w < 0.0) composed = -composed;\n worldRotation = composed;\n }\n #ifdef USE_NONRIGID_COV\n // Bone-length scaling: the palette keeps its per-axis scale and the\n // gaussian stretches with the bone.\n worldScale *= s;\n #endif\n }\n #endif\n\n #ifdef USE_VARIANT_MASK\n if (isSplatHiddenByVariantMask(splatUV)) {\n gl_Position = discardVec;\n return;\n }\n #endif\n\n // ---- Project the centre --------------------------------------------\n bool ortho = projectionMatrix[3][3] == 1.0;\n vec4 centerView = viewMatrix * vec4(worldCenter, 1.0);\n if (!ortho && centerView.z > 0.0) {\n gl_Position = discardVec;\n return;\n }\n vec4 centerProj = projectionMatrix * centerView;\n centerProj.z = clamp(centerProj.z, -abs(centerProj.w), abs(centerProj.w));\n\n // ---- Project the covariance to a screen-space ellipse ----------------\n vec3 covA, covB;\n computeCovariance(worldRotation.wxyz, worldScale, covA, covB);\n mat3 Vrk = mat3(\n covA.x, covA.y, covA.z,\n covA.y, covB.x, covB.y,\n covA.z, covB.y, covB.z\n );\n\n float focal = uViewport.x * projectionMatrix[0][0];\n vec3 v = centerView.xyz;\n vec3 vp = ortho ? vec3(0.0, 0.0, 1.0) : v;\n float J1 = focal / vp.z;\n vec2 J2 = -J1 / vp.z * vp.xy;\n mat3 J = mat3(\n J1, 0.0, J2.x,\n 0.0, J1, J2.y,\n 0.0, 0.0, 0.0\n );\n mat3 W = transpose(mat3(viewMatrix));\n mat3 T = W * J;\n mat3 cov = transpose(T) * Vrk * T;\n\n #ifdef USE_ANTIALIAS\n float detOrig = cov[0][0] * cov[1][1] - cov[0][1] * cov[0][1];\n float detBlur = (cov[0][0] + 0.3) * (cov[1][1] + 0.3) - cov[0][1] * cov[0][1];\n float aaFactor = sqrt(max(detOrig / detBlur, 0.0));\n #endif\n\n float diagonal1 = cov[0][0] + 0.3;\n float offDiagonal = cov[0][1];\n float diagonal2 = cov[1][1] + 0.3;\n float mid = 0.5 * (diagonal1 + diagonal2);\n float radius = length(vec2((diagonal1 - diagonal2) / 2.0, offDiagonal));\n float lambda1 = mid + radius;\n float lambda2 = max(mid - radius, 0.1);\n\n float vmin = min(1024.0, min(uViewport.x, uViewport.y));\n float l1 = 2.0 * min(sqrt(2.0 * lambda1), vmin);\n float l2 = 2.0 * min(sqrt(2.0 * lambda2), vmin);\n if (max(l1, l2) < uMinPixelSize) {\n gl_Position = discardVec;\n return;\n }\n\n // Cull splats whose ellipse lies wholly off-screen.\n vec2 c = centerProj.ww / uViewport;\n if (any(greaterThan(abs(centerProj.xy) - vec2(max(l1, l2)) * c, centerProj.ww))) {\n gl_Position = discardVec;\n return;\n }\n\n vec2 diagonalVector = normalize(vec2(offDiagonal, lambda1 - diagonal1));\n vec2 v1 = l1 * diagonalVector;\n vec2 v2 = l2 * vec2(diagonalVector.y, -diagonalVector.x);\n vec2 cornerUV = position.xy;\n vec2 offset = (cornerUV.x * v1 + cornerUV.y * v2) * c;\n\n // ---- Colour -----------------------------------------------------------\n vec4 clr = texelFetch(tColor, splatUV, 0);\n #ifdef USE_ANTIALIAS\n clr.a *= aaFactor;\n #endif\n\n clr.rgb *= computeLitFactor(worldCenter);\n clr.rgb = mix(clr.rgb, uTint.rgb, clamp(uTint.a, 0.0, 1.0));\n // Identity grade is a true no-op: skipping it keeps HDR splat colours unclamped.\n if (uGrade.x != 1.0 || uGrade.y != 1.0) {\n clr.rgb = (clr.rgb - 0.5) * uGrade.x + 0.5;\n float luma = dot(clr.rgb, vec3(0.2126, 0.7152, 0.0722));\n clr.rgb = mix(vec3(luma), clr.rgb, uGrade.y);\n clr.rgb = clamp(clr.rgb, 0.0, 1.0);\n }\n\n if (255.0 * clr.a <= 1.0) {\n gl_Position = discardVec;\n return;\n }\n\n // Shrink the quad to where the gaussian is still above 1/255: fewer\n // fragments, identical pixels.\n float clip = min(1.0, sqrt(log(255.0 * clr.a)) * 0.5);\n offset *= clip;\n\n gl_Position = centerProj + vec4(offset, 0.0, 0.0);\n gaussianUV = cornerUV * clip;\n\n vec3 rgb = max(clr.rgb, 0.0);\n if (uOutputLinear > 0.5) rgb = sRGBToLinear(rgb);\n gaussianColor = vec4(rgb, clr.a);\n}\n";
1
+ /**
2
+ * The vertex stage, with a game colour hook (`USE_COLOR_MODIFIER`) spliced in
3
+ * where given. See SplatColorModifier.
4
+ */
5
+ export declare function splatVertexGLSL(colorModifier?: string): string;
2
6
  export declare const SPLAT_FRAGMENT_GLSL = "\nprecision highp float;\n\nin mediump vec2 gaussianUV;\nin mediump vec4 gaussianColor;\n\nlayout(location = 0) out highp vec4 fragColor;\n\nconst float EXP4 = exp(-4.0);\nconst float INV_EXP4 = 1.0 / (1.0 - EXP4);\n\n// exp(-4x) rescaled to hit exactly 0 at the quad edge (x = 1).\nfloat normExp(float x) {\n return (exp(x * -4.0) - EXP4) * INV_EXP4;\n}\n\nvoid main(void) {\n mediump float A = dot(gaussianUV, gaussianUV);\n if (A > 1.0) {\n discard;\n }\n mediump float alpha = normExp(A) * gaussianColor.a;\n if (alpha < 1.0 / 255.0) {\n discard;\n }\n // Premultiplied.\n fragColor = vec4(gaussianColor.rgb * alpha, alpha);\n}\n";
@@ -28,6 +28,10 @@ export declare class WebGLSplatImpl implements SplatRenderImpl {
28
28
  private _lastDx;
29
29
  private _lastDy;
30
30
  private _lastDz;
31
+ /** The importance ordering the worker already holds, if any. */
32
+ private _sentSubset;
33
+ /** Names of the colour hook's uniforms currently on the material. */
34
+ private _hookUniforms;
31
35
  /**
32
36
  * @param asyncSort - Sort in a worker and keep drawing the previous order
33
37
  * meanwhile. Right for large static splats; wrong for skinned ones, whose
@@ -40,6 +44,8 @@ export declare class WebGLSplatImpl implements SplatRenderImpl {
40
44
  requestSort(): void;
41
45
  /** Rebuild the shader variant after a feature toggle on the splat. */
42
46
  syncDefines(): void;
47
+ /** Point the relight uniforms at the splat's current binding. */
48
+ syncRelight(): void;
43
49
  /** The bone textures are the splat's own; flagging them is all there is to do. */
44
50
  syncBoneData(): void;
45
51
  /** Group ids live in the splat's own texture, which it flags itself. */