@viggle/splat-engine-three 0.2.0 → 0.4.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.
@@ -116,6 +116,49 @@ export declare const SplatQuality: {
116
116
  * application wants - a character deliberately drawn over the scene.
117
117
  */
118
118
  depthOcclusion: boolean;
119
+ /**
120
+ * Alpha at which a splat writes depth, so that a splat object drawn later
121
+ * is hidden behind the solid parts of one drawn earlier. `0` (the default)
122
+ * writes no depth: the behaviour before this setting existed.
123
+ *
124
+ * Every splat object is sorted and drawn on its own, so where two of them
125
+ * overlap - a weapon in a hand, two fighters in a clinch, a character
126
+ * behind a prop - whichever draws second paints over the other across the
127
+ * whole overlap, whatever is really in front. The PlayCanvas build sorts
128
+ * every splat on a layer together and does not have the problem. With this
129
+ * on, each splat object follows its colour draw with a depth-only draw of
130
+ * its solid parts: the fragments of single splats whose alpha (the
131
+ * gaussian's falloff times the splat's opacity) reaches this value. An
132
+ * object drawn after it depth-tests against that, so its parts behind the
133
+ * first object's solid parts are hidden; its parts in front paint over it,
134
+ * as they should. An object never tests against its own depth, so one that
135
+ * overlaps nothing draws exactly as it did.
136
+ *
137
+ * `0.1`-`0.2` came closest to the PlayCanvas build in the A/B suite's
138
+ * overlap cases (a staff through a hand). Lower, the faint edges of the
139
+ * first object hide the second; higher, too little of a character is solid
140
+ * enough to hide anything.
141
+ *
142
+ * What it costs:
143
+ * - A second, depth-only draw of every splat object. Its quads are cut to
144
+ * where a splat is above this alpha, so the fragments are few; the vertex
145
+ * work, which under WebGL includes the skinning, is paid twice.
146
+ * - Where the first object is faint but above this alpha, it hides the
147
+ * second outright instead of letting it show through: a harder edge
148
+ * where the two overlap.
149
+ * - Where the first object is fainter than this alpha, the second still
150
+ * paints over it, as before.
151
+ * - The alpha is taken after {@link Splat.setOpacity}, so an object fading
152
+ * out keeps hiding what is behind it at its cores until its opacity
153
+ * falls below this value. Opt a fading object out with its own
154
+ * {@link Splat.depthWriteAlpha} for the fade.
155
+ * - Splats now hide whatever draws after them in depth: transparent meshes
156
+ * and particles behind a character, and post-processing that reads the
157
+ * depth buffer sees them.
158
+ *
159
+ * Read per frame. A splat's own {@link Splat.depthWriteAlpha} overrides it.
160
+ */
161
+ depthWriteAlpha: number;
119
162
  /**
120
163
  * Collect {@link SplatQuality.timings}. Off by default.
121
164
  *
@@ -158,6 +201,8 @@ export declare const SplatQuality: {
158
201
  /** Restore every knob to its default. Call when tearing the engine down. */
159
202
  resetStatics(): void;
160
203
  };
204
+ /** The depth-write alpha for one splat: its own setting, or else the global one. `0` is off. */
205
+ export declare function effectiveDepthWriteAlpha(splatAlpha: number | null): number;
161
206
  /** The effective sub-pixel cull for one splat: its own floor or the global one. */
162
207
  export declare function effectiveMinPixelSize(splatMinPixelSize: number): number;
163
208
  /**
@@ -32,6 +32,8 @@ export declare class SplatMesh extends Mesh {
32
32
  private readonly _engine;
33
33
  private readonly _asyncSort;
34
34
  private _impl;
35
+ /** Set by the first of this frame's two draws, which prepared it, for the second. */
36
+ private _prepared;
35
37
  /**
36
38
  * @param asyncSort - See {@link SplatBackend.createImpl}.
37
39
  * @internal Construct a {@link Splat} instead; it creates its own mesh.
@@ -48,7 +50,18 @@ export declare class SplatMesh extends Mesh {
48
50
  syncBoneData(): void;
49
51
  syncVariantGroups(): void;
50
52
  syncRelight(): void;
51
- onBeforeRender(renderer: unknown, _scene: unknown, camera: Camera): void;
53
+ onBeforeRender(renderer: unknown, _scene: unknown, camera: Camera, _geometry?: unknown, material?: unknown): void;
54
+ /**
55
+ * Draw the depth group from the next frame on when this splat writes
56
+ * depth, and only the colour group when it does not. The render list for
57
+ * this frame is already made.
58
+ *
59
+ * Both groups are transparent, so they draw in the transparent list one
60
+ * after the other: three.js sorts by render order, then depth, then object,
61
+ * and keeps a group's order within that. The depth this object writes is
62
+ * there for the splat objects drawn after it, never for its own colour.
63
+ */
64
+ private _syncDepthWrite;
52
65
  /**
53
66
  * A second mesh drawing the same splat data, at the same transform. The
54
67
  * decoded data is shared; the GPU copy of it is not.
@@ -102,6 +102,12 @@ export declare class Splat {
102
102
  readonly localBounds: Box3;
103
103
  /** Discard splats smaller than this many pixels on screen. `0` draws everything. */
104
104
  minPixelSize: number;
105
+ /**
106
+ * This splat's own {@link SplatQuality.depthWriteAlpha}: the alpha above which
107
+ * it writes depth. `null` (the default) follows the global setting; `0`
108
+ * never writes depth, whatever the global one says.
109
+ */
110
+ depthWriteAlpha: number | null;
105
111
  private _activeSplatCount;
106
112
  private _importanceOrder;
107
113
  /** `_importanceOrder` inverted: each splat's place in it. @internal */
@@ -3,4 +3,4 @@
3
3
  * where given. See SplatColorModifier.
4
4
  */
5
5
  export declare function splatVertexGLSL(colorModifier?: string): string;
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";
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\n#ifdef DEPTH_ONLY\n// SplatQuality.depthWriteAlpha: the alpha at which a fragment writes depth.\nuniform float uDepthAlpha;\n#endif\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 #ifdef DEPTH_ONLY\n if (alpha < uDepthAlpha) {\n discard;\n }\n fragColor = vec4(0.0);\n #else\n if (alpha < 1.0 / 255.0) {\n discard;\n }\n // Premultiplied.\n fragColor = vec4(gaussianColor.rgb * alpha, alpha);\n #endif\n}\n";
@@ -15,6 +15,7 @@ import type { Splat } from '../splat';
15
15
  export declare class WebGLSplatImpl implements SplatRenderImpl {
16
16
  readonly geometry: InstancedBufferGeometry;
17
17
  readonly material: RawShaderMaterial;
18
+ readonly depthMaterial: RawShaderMaterial;
18
19
  /** The depth sort runs on the CPU, so it needs CPU-side centres. */
19
20
  readonly needsCpuCenters = true;
20
21
  private readonly _host;
@@ -29,6 +29,7 @@ export declare const MAX_VARIANT_GROUPS = 64;
29
29
  export declare class WebGPUSplatImpl implements SplatRenderImpl {
30
30
  readonly geometry: InstancedBufferGeometry;
31
31
  readonly material: NodeMaterial;
32
+ readonly depthMaterial: NodeMaterial;
32
33
  /** Skinning for the sort happens in compute; the CPU never touches a splat. */
33
34
  readonly needsCpuCenters = false;
34
35
  private readonly _host;
package/dist/webgpu.js CHANGED
@@ -45,6 +45,7 @@ import {
45
45
  JsonVfxInstance,
46
46
  JsonVfxPrefab,
47
47
  LOWER_BODY_BONE_NAMES,
48
+ Mat4,
48
49
  MeshFlash,
49
50
  MeshLayerRenderer,
50
51
  NUM_BODY_PARTS,
@@ -55,6 +56,7 @@ import {
55
56
  PointLight,
56
57
  Pose,
57
58
  PostFX,
59
+ Quat,
58
60
  Ragdoll,
59
61
  RigidBody,
60
62
  Scene,
@@ -82,6 +84,7 @@ import {
82
84
  ThirdPersonCamera,
83
85
  UPPER_BODY_BONE_NAMES,
84
86
  VSplatLoader,
87
+ Vec3,
85
88
  VfxLayerRegistry,
86
89
  VfxPool,
87
90
  VfxStage,
@@ -92,6 +95,7 @@ import {
92
95
  bodyPartLabel,
93
96
  buildBoneToGroup,
94
97
  buildProxyMesh,
98
+ buildSourceBoneRemap,
95
99
  buildStretch,
96
100
  buildVfxQuadMesh,
97
101
  buildVfxRingMesh,
@@ -105,12 +109,15 @@ import {
105
109
  createConeTwistJoint,
106
110
  createGeneric6DofJoint,
107
111
  createHingeJoint,
112
+ createPointToPointJoint,
108
113
  decodeCharacterBundle,
109
114
  decodeSplatFile,
110
115
  decodeSpz,
111
116
  defaultLayerRegistry,
112
117
  defaultProxySettings,
118
+ effectiveDepthWriteAlpha,
113
119
  effectiveMinPixelSize,
120
+ evictExpired,
114
121
  extractSurface,
115
122
  getRelightPlaceholder,
116
123
  getVfxMesh,
@@ -140,10 +147,11 @@ import {
140
147
  setAssetFetch,
141
148
  setBinFetch,
142
149
  setGlbLoader,
150
+ setPlayCanvasLightColor,
143
151
  setShareSplatResources,
144
152
  uninstallFetchInterceptor,
145
153
  validateShaderGLSL
146
- } from "./chunks/chunk-BHNNSHJG.js";
154
+ } from "./chunks/chunk-SASRTGRD.js";
147
155
 
148
156
  // src/webgpu.ts
149
157
  import { WebGPURenderer } from "three/webgpu";
@@ -645,6 +653,7 @@ import {
645
653
  InstancedBufferGeometry,
646
654
  Matrix3,
647
655
  Matrix4,
656
+ NoBlending as NoBlending2,
648
657
  NodeMaterial as NodeMaterial4,
649
658
  Quaternion,
650
659
  SRGBColorSpace,
@@ -826,6 +835,7 @@ var INPUT_SLOTS = 100;
826
835
  var WebGPUSplatImpl = class {
827
836
  geometry;
828
837
  material;
838
+ depthMaterial;
829
839
  /** Skinning for the sort happens in compute; the CPU never touches a splat. */
830
840
  needsCpuCenters = false;
831
841
  _host;
@@ -882,6 +892,10 @@ var WebGPUSplatImpl = class {
882
892
  // two expressions it feeds reduce to what they were before the cutoff was
883
893
  // a setting. See SplatQuality.quadAlphaCutoff.
884
894
  alphaCutoffScale: uniform5(255),
895
+ // The depth write (SplatQuality.depthWriteAlpha): 1 / its alpha, which
896
+ // its quads are cut to, and the alpha itself, which a fragment must reach.
897
+ depthCutoffScale: uniform5(0),
898
+ depthAlpha: uniform5(2),
885
899
  // x: far depth, y: 1 / (far - near), along the view axis.
886
900
  sortRange: uniform5(new Vector23(1, 1)),
887
901
  tint: uniform5(new Vector44(1, 1, 1, 0)),
@@ -920,8 +934,19 @@ var WebGPUSplatImpl = class {
920
934
  material.forceSinglePass = true;
921
935
  material.premultipliedAlpha = true;
922
936
  material.fog = false;
937
+ const depth = new NodeMaterial4();
938
+ depth.name = "SplatDepthWrite";
939
+ depth.transparent = true;
940
+ depth.depthTest = true;
941
+ depth.depthWrite = true;
942
+ depth.colorWrite = false;
943
+ depth.blending = NoBlending2;
944
+ depth.side = DoubleSide;
945
+ depth.forceSinglePass = true;
946
+ depth.fog = false;
923
947
  this.geometry = geometry;
924
948
  this.material = material;
949
+ this.depthMaterial = depth;
925
950
  this._host = host;
926
951
  this._splat = splat;
927
952
  this._lighting = lighting;
@@ -1327,8 +1352,8 @@ var WebGPUSplatImpl = class {
1327
1352
  workWrite.element(slot).assign(select(culled, vec43(0, 0, 2, 1), centerProj));
1328
1353
  workWrite.element(slot.add(1)).assign(select(culled, vec43(0), vec43(v1, v2)));
1329
1354
  workWrite.element(slot.add(2)).assign(vec43(rgb, select(culled, float4(0), alpha)));
1330
- const depth = (cutOn ? u.view.mul(u.model.mul(vec43(sortCenter, 1))).z : centerView.z).negate();
1331
- const normalized = clamp2(u.sortRange.x.sub(depth).mul(u.sortRange.y), 0, 1);
1355
+ const depth2 = (cutOn ? u.view.mul(u.model.mul(vec43(sortCenter, 1))).z : centerView.z).negate();
1356
+ const normalized = clamp2(u.sortRange.x.sub(depth2).mul(u.sortRange.y), 0, 1);
1332
1357
  const key = uint2(normalized.mul(SORT_BINS - 1)).toVar();
1333
1358
  sort.keysWrite.element(instanceIndex2).assign(key);
1334
1359
  sort.countFirstDigit(instanceIndex2, key);
@@ -1339,33 +1364,44 @@ var WebGPUSplatImpl = class {
1339
1364
  this._buildId++;
1340
1365
  const workRead = storage2(workAttribute, "vec4", count * 3).toReadOnly();
1341
1366
  const orderRead = sort.orderRead;
1342
- const gaussianUV = varyingProperty("vec2", "vGaussianUV");
1343
- const gaussianColor = varyingProperty("vec4", "vGaussianColor");
1367
+ const drawNodes = (cutoffScale, minAlpha) => {
1368
+ const gaussianUV = varyingProperty("vec2", "vGaussianUV");
1369
+ const gaussianColor = varyingProperty("vec4", "vGaussianColor");
1370
+ const vertex = Fn4(() => {
1371
+ const slot = orderRead.element(instanceIndex2).mul(3).toVar();
1372
+ const centerProj = workRead.element(slot).toVar();
1373
+ const axes = workRead.element(slot.add(1)).toVar();
1374
+ const shade = workRead.element(slot.add(2)).toVar();
1375
+ const clip = min(float4(1), sqrt2(log(max2(shade.w.mul(cutoffScale), 1))).mul(0.5)).toVar();
1376
+ const corner = positionGeometry.xy.toVar();
1377
+ const offset = axes.xy.mul(corner.x).add(axes.zw.mul(corner.y)).mul(clip);
1378
+ gaussianUV.assign(corner.mul(clip));
1379
+ gaussianColor.assign(shade);
1380
+ return centerProj.add(vec43(offset, 0, 0));
1381
+ })();
1382
+ const color = Fn4(() => {
1383
+ const A = dot2(gaussianUV, gaussianUV).toVar();
1384
+ If3(A.greaterThan(1), () => {
1385
+ Discard();
1386
+ });
1387
+ const alpha = exp(A.mul(-4)).sub(EXP4).mul(INV_EXP4).mul(gaussianColor.w).toVar();
1388
+ If3(alpha.lessThan(minAlpha), () => {
1389
+ Discard();
1390
+ });
1391
+ return vec43(gaussianColor.xyz, alpha);
1392
+ })();
1393
+ return { vertex, color };
1394
+ };
1395
+ const draw = drawNodes(u.alphaCutoffScale, 1 / 255);
1344
1396
  const material = this.material;
1345
- material.vertexNode = Fn4(() => {
1346
- const slot = orderRead.element(instanceIndex2).mul(3).toVar();
1347
- const centerProj = workRead.element(slot).toVar();
1348
- const axes = workRead.element(slot.add(1)).toVar();
1349
- const shade = workRead.element(slot.add(2)).toVar();
1350
- const clip = min(float4(1), sqrt2(log(max2(shade.w.mul(u.alphaCutoffScale), 1))).mul(0.5)).toVar();
1351
- const corner = positionGeometry.xy.toVar();
1352
- const offset = axes.xy.mul(corner.x).add(axes.zw.mul(corner.y)).mul(clip);
1353
- gaussianUV.assign(corner.mul(clip));
1354
- gaussianColor.assign(shade);
1355
- return centerProj.add(vec43(offset, 0, 0));
1356
- })();
1357
- material.colorNode = Fn4(() => {
1358
- const A = dot2(gaussianUV, gaussianUV).toVar();
1359
- If3(A.greaterThan(1), () => {
1360
- Discard();
1361
- });
1362
- const alpha = exp(A.mul(-4)).sub(EXP4).mul(INV_EXP4).mul(gaussianColor.w).toVar();
1363
- If3(alpha.lessThan(1 / 255), () => {
1364
- Discard();
1365
- });
1366
- return vec43(gaussianColor.xyz, alpha);
1367
- })();
1397
+ material.vertexNode = draw.vertex;
1398
+ material.colorNode = draw.color;
1368
1399
  material.needsUpdate = true;
1400
+ const depthDraw = drawNodes(u.depthCutoffScale, u.depthAlpha);
1401
+ const depth = this.depthMaterial;
1402
+ depth.vertexNode = depthDraw.vertex;
1403
+ depth.colorNode = depthDraw.color;
1404
+ depth.needsUpdate = true;
1369
1405
  }
1370
1406
  beforeRender(renderer, camera) {
1371
1407
  if (!SplatQuality.passTimings) {
@@ -1421,7 +1457,11 @@ var WebGPUSplatImpl = class {
1421
1457
  u.alphaCutoffScale.value = 1 / Math.max(1 / 65535, SplatQuality.quadAlphaCutoff);
1422
1458
  if (this.material.depthTest !== SplatQuality.depthOcclusion) {
1423
1459
  this.material.depthTest = SplatQuality.depthOcclusion;
1460
+ this.depthMaterial.depthTest = SplatQuality.depthOcclusion;
1424
1461
  }
1462
+ const depthAlpha = effectiveDepthWriteAlpha(splat.depthWriteAlpha);
1463
+ u.depthCutoffScale.value = depthAlpha > 0 ? 1 / depthAlpha : 0;
1464
+ u.depthAlpha.value = depthAlpha > 0 ? depthAlpha : 2;
1425
1465
  u.tint.value.copy(splat.tint);
1426
1466
  u.grade.value.copy(splat.grade);
1427
1467
  u.effects.value.copy(splat.effects);
@@ -1519,6 +1559,7 @@ var WebGPUSplatImpl = class {
1519
1559
  dispose() {
1520
1560
  this.geometry.dispose();
1521
1561
  this.material.dispose();
1562
+ this.depthMaterial.dispose();
1522
1563
  this._retired.push({ nodes: [...this._projectNodes, ...this._sortNodes], buffers: this._buffers });
1523
1564
  this._projectNodes = [];
1524
1565
  this._sortNodes = [];
@@ -1718,6 +1759,7 @@ export {
1718
1759
  LOWER_BODY_BONE_NAMES,
1719
1760
  MAX_POINT_LIGHTS,
1720
1761
  MAX_VARIANT_GROUPS,
1762
+ Mat4,
1721
1763
  MeshFlash,
1722
1764
  MeshLayerRenderer,
1723
1765
  NUM_BODY_PARTS,
@@ -1728,6 +1770,7 @@ export {
1728
1770
  PointLight,
1729
1771
  Pose,
1730
1772
  PostFX,
1773
+ Quat,
1731
1774
  Ragdoll,
1732
1775
  RigidBody,
1733
1776
  Scene,
@@ -1756,6 +1799,7 @@ export {
1756
1799
  ThirdPersonCamera,
1757
1800
  UPPER_BODY_BONE_NAMES,
1758
1801
  VSplatLoader,
1802
+ Vec3,
1759
1803
  VfxLayerRegistry,
1760
1804
  VfxPool,
1761
1805
  VfxStage,
@@ -1765,6 +1809,7 @@ export {
1765
1809
  bodyPartLabel,
1766
1810
  buildBoneToGroup,
1767
1811
  buildProxyMesh,
1812
+ buildSourceBoneRemap,
1768
1813
  buildStretch,
1769
1814
  buildVfxQuadMesh,
1770
1815
  buildVfxRingMesh,
@@ -1778,11 +1823,13 @@ export {
1778
1823
  createConeTwistJoint,
1779
1824
  createGeneric6DofJoint,
1780
1825
  createHingeJoint,
1826
+ createPointToPointJoint,
1781
1827
  decodeCharacterBundle,
1782
1828
  decodeSplatFile,
1783
1829
  decodeSpz,
1784
1830
  defaultLayerRegistry,
1785
1831
  defaultProxySettings,
1832
+ evictExpired,
1786
1833
  extractSurface,
1787
1834
  getVfxMesh,
1788
1835
  indexAssetCache,
@@ -1805,6 +1852,7 @@ export {
1805
1852
  setAssetFetch,
1806
1853
  setBinFetch,
1807
1854
  setGlbLoader,
1855
+ setPlayCanvasLightColor,
1808
1856
  setShareSplatResources,
1809
1857
  uninstallFetchInterceptor,
1810
1858
  validateShaderGLSL