@viggle/splat-engine-three 0.3.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.
package/dist/index.js CHANGED
@@ -140,7 +140,7 @@ import {
140
140
  setShareSplatResources,
141
141
  uninstallFetchInterceptor,
142
142
  validateShaderGLSL
143
- } from "./chunks/chunk-2GKWT24B.js";
143
+ } from "./chunks/chunk-SASRTGRD.js";
144
144
  export {
145
145
  ALL_BODY_PARTS,
146
146
  Animation,
@@ -399,7 +399,9 @@ export declare class Character {
399
399
  * animates in lockstep) but on `layerIds`. With the body occluded by real
400
400
  * objects, this copy is what shows through obstacles: give it a see-through
401
401
  * look with its own {@link Splat.setOpacity} or {@link Splat.setColorModifier}
402
- * (the PlayCanvas build's `applyOverlaySplatStyle` is not ported).
402
+ * (the PlayCanvas build's `applyOverlaySplatStyle` is not ported). It
403
+ * writes no depth under {@link SplatQuality.depthWriteAlpha}, so it never
404
+ * hides what it is meant to show through.
403
405
  * Synchronous: reuses the decoded data.
404
406
  */
405
407
  addOverlaySplat(layerIds: number[]): Splat;
@@ -15,6 +15,12 @@ import type { Splat } from './splat';
15
15
  export interface SplatRenderImpl {
16
16
  readonly geometry: BufferGeometry;
17
17
  readonly material: Material;
18
+ /**
19
+ * The depth-only material of {@link SplatQuality.depthWriteAlpha}: drawn as
20
+ * a second group of the same geometry, in the transparent list straight
21
+ * after {@link material}. Its uniforms are kept current by {@link beforeRender}.
22
+ */
23
+ readonly depthMaterial: Material;
18
24
  /**
19
25
  * Whether the splat's centres must be re-skinned on the CPU every frame.
20
26
  * True when the depth sort runs on the CPU; false when the GPU skins for its
@@ -36,7 +42,10 @@ export interface SplatRenderImpl {
36
42
  syncVariantGroups(): void;
37
43
  /** Rebind the relight inputs after {@link Splat.setRelightBinding} swapped one binding for another. */
38
44
  syncRelight(): void;
39
- /** Called from the host mesh's `onBeforeRender`, once per draw. */
45
+ /**
46
+ * Called from the host mesh's `onBeforeRender`: once per frame, before
47
+ * whichever of the two draws comes first.
48
+ */
40
49
  beforeRender(renderer: unknown, camera: Camera): void;
41
50
  /** Release GPU resources. The splat's own textures are not this object's to free. */
42
51
  dispose(): void;
@@ -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
@@ -115,6 +115,7 @@ import {
115
115
  decodeSpz,
116
116
  defaultLayerRegistry,
117
117
  defaultProxySettings,
118
+ effectiveDepthWriteAlpha,
118
119
  effectiveMinPixelSize,
119
120
  evictExpired,
120
121
  extractSurface,
@@ -150,7 +151,7 @@ import {
150
151
  setShareSplatResources,
151
152
  uninstallFetchInterceptor,
152
153
  validateShaderGLSL
153
- } from "./chunks/chunk-2GKWT24B.js";
154
+ } from "./chunks/chunk-SASRTGRD.js";
154
155
 
155
156
  // src/webgpu.ts
156
157
  import { WebGPURenderer } from "three/webgpu";
@@ -652,6 +653,7 @@ import {
652
653
  InstancedBufferGeometry,
653
654
  Matrix3,
654
655
  Matrix4,
656
+ NoBlending as NoBlending2,
655
657
  NodeMaterial as NodeMaterial4,
656
658
  Quaternion,
657
659
  SRGBColorSpace,
@@ -833,6 +835,7 @@ var INPUT_SLOTS = 100;
833
835
  var WebGPUSplatImpl = class {
834
836
  geometry;
835
837
  material;
838
+ depthMaterial;
836
839
  /** Skinning for the sort happens in compute; the CPU never touches a splat. */
837
840
  needsCpuCenters = false;
838
841
  _host;
@@ -889,6 +892,10 @@ var WebGPUSplatImpl = class {
889
892
  // two expressions it feeds reduce to what they were before the cutoff was
890
893
  // a setting. See SplatQuality.quadAlphaCutoff.
891
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),
892
899
  // x: far depth, y: 1 / (far - near), along the view axis.
893
900
  sortRange: uniform5(new Vector23(1, 1)),
894
901
  tint: uniform5(new Vector44(1, 1, 1, 0)),
@@ -927,8 +934,19 @@ var WebGPUSplatImpl = class {
927
934
  material.forceSinglePass = true;
928
935
  material.premultipliedAlpha = true;
929
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;
930
947
  this.geometry = geometry;
931
948
  this.material = material;
949
+ this.depthMaterial = depth;
932
950
  this._host = host;
933
951
  this._splat = splat;
934
952
  this._lighting = lighting;
@@ -1334,8 +1352,8 @@ var WebGPUSplatImpl = class {
1334
1352
  workWrite.element(slot).assign(select(culled, vec43(0, 0, 2, 1), centerProj));
1335
1353
  workWrite.element(slot.add(1)).assign(select(culled, vec43(0), vec43(v1, v2)));
1336
1354
  workWrite.element(slot.add(2)).assign(vec43(rgb, select(culled, float4(0), alpha)));
1337
- const depth = (cutOn ? u.view.mul(u.model.mul(vec43(sortCenter, 1))).z : centerView.z).negate();
1338
- 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);
1339
1357
  const key = uint2(normalized.mul(SORT_BINS - 1)).toVar();
1340
1358
  sort.keysWrite.element(instanceIndex2).assign(key);
1341
1359
  sort.countFirstDigit(instanceIndex2, key);
@@ -1346,33 +1364,44 @@ var WebGPUSplatImpl = class {
1346
1364
  this._buildId++;
1347
1365
  const workRead = storage2(workAttribute, "vec4", count * 3).toReadOnly();
1348
1366
  const orderRead = sort.orderRead;
1349
- const gaussianUV = varyingProperty("vec2", "vGaussianUV");
1350
- 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);
1351
1396
  const material = this.material;
1352
- material.vertexNode = Fn4(() => {
1353
- const slot = orderRead.element(instanceIndex2).mul(3).toVar();
1354
- const centerProj = workRead.element(slot).toVar();
1355
- const axes = workRead.element(slot.add(1)).toVar();
1356
- const shade = workRead.element(slot.add(2)).toVar();
1357
- const clip = min(float4(1), sqrt2(log(max2(shade.w.mul(u.alphaCutoffScale), 1))).mul(0.5)).toVar();
1358
- const corner = positionGeometry.xy.toVar();
1359
- const offset = axes.xy.mul(corner.x).add(axes.zw.mul(corner.y)).mul(clip);
1360
- gaussianUV.assign(corner.mul(clip));
1361
- gaussianColor.assign(shade);
1362
- return centerProj.add(vec43(offset, 0, 0));
1363
- })();
1364
- material.colorNode = Fn4(() => {
1365
- const A = dot2(gaussianUV, gaussianUV).toVar();
1366
- If3(A.greaterThan(1), () => {
1367
- Discard();
1368
- });
1369
- const alpha = exp(A.mul(-4)).sub(EXP4).mul(INV_EXP4).mul(gaussianColor.w).toVar();
1370
- If3(alpha.lessThan(1 / 255), () => {
1371
- Discard();
1372
- });
1373
- return vec43(gaussianColor.xyz, alpha);
1374
- })();
1397
+ material.vertexNode = draw.vertex;
1398
+ material.colorNode = draw.color;
1375
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;
1376
1405
  }
1377
1406
  beforeRender(renderer, camera) {
1378
1407
  if (!SplatQuality.passTimings) {
@@ -1428,7 +1457,11 @@ var WebGPUSplatImpl = class {
1428
1457
  u.alphaCutoffScale.value = 1 / Math.max(1 / 65535, SplatQuality.quadAlphaCutoff);
1429
1458
  if (this.material.depthTest !== SplatQuality.depthOcclusion) {
1430
1459
  this.material.depthTest = SplatQuality.depthOcclusion;
1460
+ this.depthMaterial.depthTest = SplatQuality.depthOcclusion;
1431
1461
  }
1462
+ const depthAlpha = effectiveDepthWriteAlpha(splat.depthWriteAlpha);
1463
+ u.depthCutoffScale.value = depthAlpha > 0 ? 1 / depthAlpha : 0;
1464
+ u.depthAlpha.value = depthAlpha > 0 ? depthAlpha : 2;
1432
1465
  u.tint.value.copy(splat.tint);
1433
1466
  u.grade.value.copy(splat.grade);
1434
1467
  u.effects.value.copy(splat.effects);
@@ -1526,6 +1559,7 @@ var WebGPUSplatImpl = class {
1526
1559
  dispose() {
1527
1560
  this.geometry.dispose();
1528
1561
  this.material.dispose();
1562
+ this.depthMaterial.dispose();
1529
1563
  this._retired.push({ nodes: [...this._projectNodes, ...this._sortNodes], buffers: this._buffers });
1530
1564
  this._projectNodes = [];
1531
1565
  this._sortNodes = [];