@threenative/core 0.3.4 → 0.3.6
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/capabilities.json +1505 -79
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-CljaDv4D.d.ts → game-Jz4Fdoeb.d.ts} +114 -11
- package/dist/hot.d.ts +4 -4
- package/dist/index.d.ts +712 -118
- package/dist/index.js +12437 -4955
- package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
- package/dist/playtest.d.ts +6 -10
- package/dist/playtest.js +57 -24
- package/dist/react-css.d.ts +62 -0
- package/dist/react-css.js +591 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +766 -73
- package/dist/world.js +9307 -3543
- package/gpl/recipes/export_world.py +18 -1
- package/mcp/blender-server.mjs +7 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +2 -2
- package/mcp/servers.mjs +4 -4
- package/package.json +15 -9
- package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
- package/patches/three@0.185.1.patch +6594 -700
- package/scripts/apply-three-patch.mjs +62 -4
- package/src/animation-blend.ts +264 -0
- package/src/animation-composition.ts +362 -0
- package/src/animation-layers.ts +260 -0
- package/src/animation-root-motion.ts +283 -0
- package/src/animation.ts +896 -0
- package/src/assets.ts +1303 -0
- package/src/atmosphere/index.ts +335 -0
- package/src/atmosphere/luts.ts +298 -0
- package/src/atmosphere/params.ts +323 -0
- package/src/audio.ts +912 -0
- package/src/billboard.ts +124 -0
- package/src/bone-lengths.ts +157 -0
- package/src/camera-shake.ts +116 -0
- package/src/canvas-layer.ts +47 -0
- package/src/clip-audit.ts +401 -0
- package/src/clustered-batch.ts +492 -0
- package/src/clustered-mesh.ts +638 -0
- package/src/compute-driven.ts +176 -0
- package/src/compute-timing.ts +318 -0
- package/src/config.ts +593 -0
- package/src/debug.ts +82 -0
- package/src/engine-render-hook.ts +25 -0
- package/src/entities.ts +79 -0
- package/src/entity-snapshot.ts +53 -0
- package/src/flight.ts +683 -0
- package/src/fluid-field.ts +748 -0
- package/src/fluid-particles.ts +1253 -0
- package/src/frame-budget.ts +1368 -0
- package/src/game.ts +2408 -0
- package/src/geometry-capture.ts +1098 -0
- package/src/gpu-class.ts +160 -0
- package/src/gpu-frame-observation.ts +424 -0
- package/src/gpu-readback.ts +143 -0
- package/src/gpu-scene-bvh.ts +464 -0
- package/src/grounding.ts +100 -0
- package/src/hot.ts +161 -0
- package/src/import-meta.d.ts +13 -0
- package/src/index.ts +1536 -0
- package/src/input.ts +690 -0
- package/src/instanced-batch-lod.ts +283 -0
- package/src/instanced-batch.ts +274 -0
- package/src/interpolation.ts +129 -0
- package/src/launch-diagnostics.ts +161 -0
- package/src/loop.ts +574 -0
- package/src/matrix-world.ts +245 -0
- package/src/merge-parts.ts +812 -0
- package/src/model-lod.ts +1315 -0
- package/src/net-protocol.ts +333 -0
- package/src/net-session.ts +477 -0
- package/src/net.ts +80 -0
- package/src/ocean/fft.ts +72 -0
- package/src/ocean/spectral.ts +728 -0
- package/src/particle-significance.ts +102 -0
- package/src/particles.ts +648 -0
- package/src/path-follow.ts +175 -0
- package/src/picking.ts +250 -0
- package/src/pipeline-census.ts +1566 -0
- package/src/platform.ts +210 -0
- package/src/playtest.ts +850 -0
- package/src/pointer-events.ts +411 -0
- package/src/pose-measure.ts +435 -0
- package/src/profiling/FrameCounters.ts +231 -0
- package/src/profiling/Spans.ts +548 -0
- package/src/profiling/opacity-convention.ts +21 -0
- package/src/profiling/render-list-validate.ts +175 -0
- package/src/profiling/render-trap-audit.ts +84 -0
- package/src/profiling/scene-warning.ts +190 -0
- package/src/profiling/span-probes.ts +191 -0
- package/src/profiling/unlit-foliage-warning.ts +149 -0
- package/src/projection-apply.ts +1529 -0
- package/src/projection-marker.ts +142 -0
- package/src/projection-plan.ts +1258 -0
- package/src/projection-skinned.ts +419 -0
- package/src/projection-stability.ts +409 -0
- package/src/projection-uniform.ts +328 -0
- package/src/random.ts +41 -0
- package/src/react-css.ts +604 -0
- package/src/react-glyphs.ts +114 -0
- package/src/react-host.ts +576 -0
- package/src/react-layout.ts +265 -0
- package/src/react.ts +60 -0
- package/src/render/alpha-antialiasing.ts +159 -0
- package/src/render/batched-velocity.ts +126 -0
- package/src/render/chain.ts +1021 -0
- package/src/render/daylight.ts +189 -0
- package/src/render/depth-pyramid.ts +596 -0
- package/src/render/foliage-alpha.ts +166 -0
- package/src/render/material-key.ts +60 -0
- package/src/render/mesh-pool.ts +144 -0
- package/src/render/probe-volume.ts +1668 -0
- package/src/render/resolution-subrect.ts +253 -0
- package/src/render/velocity.ts +442 -0
- package/src/render/virtual-shadow-pages.ts +827 -0
- package/src/render/virtual-shadow-partial.ts +174 -0
- package/src/render/virtual-shadow.ts +3330 -0
- package/src/render/world-impostor-surface.ts +722 -0
- package/src/render/world-impostor.ts +558 -0
- package/src/render-camera-cull.ts +441 -0
- package/src/render-pass-budget.ts +501 -0
- package/src/renderProjection.ts +758 -0
- package/src/renderer-config.ts +127 -0
- package/src/renderer.ts +1847 -0
- package/src/replay-protocol.ts +85 -0
- package/src/replay.ts +205 -0
- package/src/resolution-scaler.ts +819 -0
- package/src/rig-preparation.ts +271 -0
- package/src/ripple-field.ts +432 -0
- package/src/scale.ts +109 -0
- package/src/scene.ts +239 -0
- package/src/schedule.ts +155 -0
- package/src/skeletal-mesh.ts +61 -0
- package/src/skeleton.ts +100 -0
- package/src/snow-field.ts +744 -0
- package/src/softbody-topology.ts +269 -0
- package/src/softbody.ts +516 -0
- package/src/sprite-animator.ts +222 -0
- package/src/startup-readiness.ts +386 -0
- package/src/state.ts +66 -0
- package/src/static-transform.ts +274 -0
- package/src/storage-buffer.ts +253 -0
- package/src/streaming.ts +308 -0
- package/src/target-fps.ts +92 -0
- package/src/terrain-jobs-worker.ts +17 -0
- package/src/terrain-jobs.ts +353 -0
- package/src/textures.ts +39 -0
- package/src/tracers.ts +237 -0
- package/src/ui-bridge.ts +368 -0
- package/src/ui-hit-regions.ts +380 -0
- package/src/ui-layer.ts +83 -0
- package/src/ui-state.ts +220 -0
- package/src/version.ts +2 -0
- package/src/viewport.ts +253 -0
- package/src/warmup.ts +1357 -0
- package/src/water-surface.ts +384 -0
- package/src/wave-field.ts +524 -0
- package/src/world-capabilities.ts +131 -0
- package/src/world-cell-proxy.ts +392 -0
- package/src/world-cells.ts +10564 -0
- package/src/world-gpu-scene.ts +3354 -0
- package/src/world-heightmap.ts +82 -0
- package/src/world-package.ts +469 -0
- package/src/world-passes.ts +582 -0
- package/src/world-region.ts +17 -0
- package/src/world-terrain-splat.ts +564 -0
- package/src/world-tiles.ts +3826 -0
- package/src/world-topology.ts +370 -0
- package/src/world-validate.ts +48 -0
- package/src/world.ts +805 -0
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
import type { Material, Texture } from "three";
|
|
2
|
+
import { dFdx, dFdy, float, length, log2, max, uv, vec2 } from "three/tsl";
|
|
3
|
+
import {
|
|
4
|
+
MeshBasicNodeMaterial,
|
|
5
|
+
MeshPhysicalNodeMaterial,
|
|
6
|
+
MeshStandardNodeMaterial,
|
|
7
|
+
type Node,
|
|
8
|
+
type NodeMaterial,
|
|
9
|
+
} from "three/webgpu";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* How much of the mip chain's alpha loss one mip level is compensated by: Golus's `MIP_SCALE`, and
|
|
13
|
+
* the value his `Alpha To Coverage` post measures its distance with. 0.25 takes a `0.5` cutoff to
|
|
14
|
+
* 0.2 by mip 6 and no further — which is the whole of it, since 11 mips is all a 2048px map has.
|
|
15
|
+
*/
|
|
16
|
+
export const MIP_ALPHA_SCALE = 0.25;
|
|
17
|
+
|
|
18
|
+
/** The part of a GLTF material this reads. Structural, so a test stub is the same input. */
|
|
19
|
+
interface ICutoutSource {
|
|
20
|
+
readonly map?: Texture;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** The classic-to-node classes `NodeLibrary.fromMaterial` picks, for the three a GLB carries. */
|
|
24
|
+
type NodeMaterialClass = new () => NodeMaterial;
|
|
25
|
+
|
|
26
|
+
const NODE_CLASSES: ReadonlyMap<string, NodeMaterialClass> = new Map<string, NodeMaterialClass>([
|
|
27
|
+
["MeshBasicMaterial", MeshBasicNodeMaterial],
|
|
28
|
+
["MeshPhysicalMaterial", MeshPhysicalNodeMaterial],
|
|
29
|
+
["MeshStandardMaterial", MeshStandardNodeMaterial],
|
|
30
|
+
]);
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Never carried from the package's own material onto the cutout: `_listeners` would hand this
|
|
34
|
+
* material's dispose hook to the authored one, and `id`/`uuid`/`version` would make the cutout a
|
|
35
|
+
* distinct material to every cache keyed on them.
|
|
36
|
+
*/
|
|
37
|
+
const UNSYNCED = new Set(["_listeners", "id", "uuid", "version"]);
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Alpha loss compensation for one mip level, as Golus's post multiplies it.
|
|
41
|
+
*
|
|
42
|
+
* The fix, in the form his improved shader uses: raise the alpha by the mip level instead of
|
|
43
|
+
* lowering it, which is the same comparison as dividing the cutoff — `a * scale > c` and
|
|
44
|
+
* `a > c / scale` are one inequality.
|
|
45
|
+
*/
|
|
46
|
+
export function mipScaledAlpha(alpha: number, mipLevel: number, scale = MIP_ALPHA_SCALE): number {
|
|
47
|
+
return alpha * (1 + Math.max(0, mipLevel) * scale);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** The same compensation as a cutoff: `cutoff / scale`, which is what the shader compares against. */
|
|
51
|
+
export function mipAdjustedCutoff(
|
|
52
|
+
cutoff: number,
|
|
53
|
+
mipLevel: number,
|
|
54
|
+
scale = MIP_ALPHA_SCALE,
|
|
55
|
+
): number {
|
|
56
|
+
return cutoff / (1 + Math.max(0, mipLevel) * scale);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* The mip level a fragment lands on: the uv footprint of the pixel, in texels, log2'd. This is the
|
|
61
|
+
* model of the shader form in `mipThreshold` below, for a square map.
|
|
62
|
+
*/
|
|
63
|
+
export function mipLevelFromFootprint(du: number, dv: number, texels: number): number {
|
|
64
|
+
return Math.log2(Math.max(Math.abs(du), Math.abs(dv)) * texels);
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* The mip level in the shader, from the uv derivatives and the map's own size — the surface
|
|
69
|
+
* gradient of Mikkelsen's mip selection, which is the conservative half of the texel footprint.
|
|
70
|
+
*/
|
|
71
|
+
function mipThreshold(
|
|
72
|
+
texels: readonly [number, number],
|
|
73
|
+
cutoff: number,
|
|
74
|
+
mipScale: number,
|
|
75
|
+
): Node<"float"> {
|
|
76
|
+
const size = vec2(texels[0], texels[1]);
|
|
77
|
+
const footprint = max(length(dFdx(uv()).mul(size)), length(dFdy(uv()).mul(size)));
|
|
78
|
+
const scale = float(1).add(max(log2(footprint), float(0)).mul(mipScale));
|
|
79
|
+
return float(cutoff).div(scale) as unknown as Node<"float">; // quality-allow: TSL result shape is set by construction; three 0.185 types swizzles and Fn loosely
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** The map's texel size, or `undefined` when there is no mip chain to compensate. */
|
|
83
|
+
function texelSize(map: Texture | undefined): readonly [number, number] | undefined {
|
|
84
|
+
const image = map?.image as { width?: number; height?: number } | undefined;
|
|
85
|
+
const width = image?.width;
|
|
86
|
+
const height = image?.height;
|
|
87
|
+
if (width === undefined || height === undefined) return undefined;
|
|
88
|
+
if (!(width > 0) || !(height > 0)) return undefined;
|
|
89
|
+
return [width, height];
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function nodeClassOf(material: Material): NodeMaterialClass | undefined {
|
|
93
|
+
if (Reflect.get(material, "isNodeMaterial") === true)
|
|
94
|
+
return material.constructor as NodeMaterialClass;
|
|
95
|
+
return NODE_CLASSES.get(material.type);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/** A node twin of the package's own material: its class, every value it authored, by reference. */
|
|
99
|
+
function nodeTwin(source: Material, nodeClass: NodeMaterialClass): Material {
|
|
100
|
+
// A material three already draws through nodes clones into its own class with every node copied.
|
|
101
|
+
if (Reflect.get(source, "isNodeMaterial") === true) return source.clone();
|
|
102
|
+
// A classic material needs the conversion `NodeLibrary.fromMaterial` does at draw time, done here
|
|
103
|
+
// instead so the cutoff can be a node instead of a number.
|
|
104
|
+
const twin = new nodeClass();
|
|
105
|
+
for (const key in source)
|
|
106
|
+
if (!UNSYNCED.has(key)) Reflect.set(twin, key, Reflect.get(source, key));
|
|
107
|
+
return twin;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* The mip-compensated cutoff for a source's own map, or `undefined` when it has no map and so no mip
|
|
112
|
+
* chain to compensate. Shared by every path that alpha-tests a cutout it samples at a distance: the
|
|
113
|
+
* scatter cutout above and the impostor bake, which renders a needle card into a 128 px frame.
|
|
114
|
+
*/
|
|
115
|
+
export function mipAlphaTestNode(
|
|
116
|
+
source: Material,
|
|
117
|
+
cutoff: number,
|
|
118
|
+
mipScale = MIP_ALPHA_SCALE,
|
|
119
|
+
): Node<"float"> | undefined {
|
|
120
|
+
const texels = texelSize((source as ICutoutSource).map);
|
|
121
|
+
return texels === undefined ? undefined : mipThreshold(texels, cutoff, mipScale);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* The node form of a cutout whose alpha survives the mip chain: Ben Golus's mip-level alpha
|
|
126
|
+
* compensation, as a dynamic `alphaTestNode`.
|
|
127
|
+
*
|
|
128
|
+
* Alpha-test a mipped alpha and distance deletes the surface. A 2048px needle card is nine percent
|
|
129
|
+
* opaque; at 100 m it is sampled from mip five or six, where the box filter has averaged the card
|
|
130
|
+
* down to about 0.1, and `discard` at 0.5 throws every needle away — a forest drawn as bare trunks.
|
|
131
|
+
* Compensating by the mip level is the standard repair: the deeper the mip the smaller the effective
|
|
132
|
+
* cutoff, because a deeper mip is a coarser question about the same texel, not a stricter one.
|
|
133
|
+
*
|
|
134
|
+
* The threshold is a *node* rather than a number so it reads the mip the fragment is actually on,
|
|
135
|
+
* which depends on distance, on screen size and on how the game scaled the card. `alphaTest` keeps
|
|
136
|
+
* the authored cutoff for every reader that only understands a number (`AlphaAntialiasing` counts
|
|
137
|
+
* the cutout by it), and the discard and the alpha-to-coverage ramp both read the node.
|
|
138
|
+
*
|
|
139
|
+
* Where the coverage mask is on, three resolves the edge itself —
|
|
140
|
+
* `smoothstep(alphaTestNode, alphaTestNode + fwidth(alpha), alpha)`, the derivative ramp Golus's
|
|
141
|
+
* first pass spells out by hand — so the sharpen is not repeated here; applying it twice would
|
|
142
|
+
* narrow the edge to half a pixel.
|
|
143
|
+
*
|
|
144
|
+
* What it never decides: the cutoff, the map, the colours, the geometry. Those are the game's; this
|
|
145
|
+
* only stops the sampler from throwing them away.
|
|
146
|
+
*/
|
|
147
|
+
export function cutoutSurface(
|
|
148
|
+
source: Material,
|
|
149
|
+
cutoff: number,
|
|
150
|
+
mipScale = MIP_ALPHA_SCALE,
|
|
151
|
+
): Material {
|
|
152
|
+
const nodeClass = nodeClassOf(source);
|
|
153
|
+
// A class with no node form — a Lambert card, say — keeps the plain cutout it has always drawn.
|
|
154
|
+
const cutout = nodeClass === undefined ? source.clone() : nodeTwin(source, nodeClass);
|
|
155
|
+
cutout.transparent = false;
|
|
156
|
+
cutout.depthWrite = true;
|
|
157
|
+
cutout.alphaTest = cutoff;
|
|
158
|
+
if (nodeClass !== undefined) {
|
|
159
|
+
// No map means no mip chain and no level to read, so the number is the whole cutoff.
|
|
160
|
+
const node = mipAlphaTestNode(source, cutoff, mipScale);
|
|
161
|
+
if (node !== undefined) (cutout as NodeMaterial).alphaTestNode = node;
|
|
162
|
+
}
|
|
163
|
+
// `transparent` is a program key in three, so the cutout needs its own compile.
|
|
164
|
+
cutout.needsUpdate = true;
|
|
165
|
+
return cutout;
|
|
166
|
+
}
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import { Color, type Material, type Texture, Vector2 } from "three";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Material identity by content, so a streamed world can share one surface — and one shader —
|
|
5
|
+
* between every asset that carries "the same" material. This module compares what a material draws
|
|
6
|
+
* with; it constructs nothing and decides no appearance: the canonical surface is still the first
|
|
7
|
+
* material the game's package handed over.
|
|
8
|
+
*/
|
|
9
|
+
const TEXTURE_SLOTS = [
|
|
10
|
+
"map",
|
|
11
|
+
"normalMap",
|
|
12
|
+
"roughnessMap",
|
|
13
|
+
"metalnessMap",
|
|
14
|
+
"aoMap",
|
|
15
|
+
"emissiveMap",
|
|
16
|
+
"alphaMap",
|
|
17
|
+
] as const;
|
|
18
|
+
|
|
19
|
+
function textureKey(texture: Texture | null | undefined): string {
|
|
20
|
+
if (texture === null || texture === undefined) return "-";
|
|
21
|
+
const image = texture.image as { width?: number; height?: number } | undefined;
|
|
22
|
+
const mips = (texture as { mipmaps?: readonly { data?: { byteLength?: number } }[] }).mipmaps;
|
|
23
|
+
return `${texture.name}:${String(image?.width ?? 0)}x${String(image?.height ?? 0)}:${String(mips?.[0]?.data?.byteLength ?? 0)}:${texture.flipY ? 1 : 0}`;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* What a material draws, as a key: its class, every parameter that changes the shader or the
|
|
28
|
+
* look, and each texture slot's image. Two GLBs that carry "the same" bark load two Material
|
|
29
|
+
* objects with two Texture objects over the same image, and three builds a shader per material:
|
|
30
|
+
* 569 material instances in one 2 km world were 36 materials, and their first-draw builds were
|
|
31
|
+
* 42 % of every streaming hitch. Keyed on content, the second asset reuses the first's surface.
|
|
32
|
+
* ponytail: an image is identified by name + size + first-mip bytes, which the loader keeps; a
|
|
33
|
+
* content hash of the pixels is the upgrade if two different images ever collide on all three.
|
|
34
|
+
*/
|
|
35
|
+
export function materialKey(material: Material): string {
|
|
36
|
+
const fields = material as Material & Record<string, unknown>;
|
|
37
|
+
const num = (value: unknown): string => (typeof value === "number" ? value.toFixed(4) : "-");
|
|
38
|
+
const color = (value: unknown): string => (value instanceof Color ? value.getHexString() : "-");
|
|
39
|
+
const vec = (value: unknown): string =>
|
|
40
|
+
value instanceof Vector2 ? `${value.x},${value.y}` : "-";
|
|
41
|
+
const textures: string[] = [];
|
|
42
|
+
for (const slot of TEXTURE_SLOTS) textures.push(textureKey(fields[slot] as Texture | undefined));
|
|
43
|
+
return [
|
|
44
|
+
material.type,
|
|
45
|
+
material.transparent ? 1 : 0,
|
|
46
|
+
num(material.alphaTest),
|
|
47
|
+
material.side,
|
|
48
|
+
material.vertexColors ? 1 : 0,
|
|
49
|
+
num(material.opacity),
|
|
50
|
+
material.depthWrite ? 1 : 0,
|
|
51
|
+
color(fields.color),
|
|
52
|
+
color(fields.emissive),
|
|
53
|
+
num(fields.emissiveIntensity),
|
|
54
|
+
num(fields.roughness),
|
|
55
|
+
num(fields.metalness),
|
|
56
|
+
vec(fields.normalScale),
|
|
57
|
+
fields.flatShading === true ? 1 : 0,
|
|
58
|
+
...textures,
|
|
59
|
+
].join("|");
|
|
60
|
+
}
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
import { type BufferGeometry, InstancedMesh, type Material } from "three";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* A pool of parked `InstancedMesh`es, keyed by the parts they draw.
|
|
5
|
+
*
|
|
6
|
+
* Three's WebGPU renderer keys its render-object/node cache by `object.uuid`, so every new
|
|
7
|
+
* InstancedMesh costs a full NodeBuilder shader build in the main pass and in every shadow pass — a
|
|
8
|
+
* streamed world minting one per cell pays it over and over. A pool hit is not a copy: it is the
|
|
9
|
+
* same object, so the node three built for it is still there. What the pool cannot do is invent a
|
|
10
|
+
* first draw, so the mints that stay mints are counted by the caller, not hidden.
|
|
11
|
+
*
|
|
12
|
+
* The smallest capacity a pooled buffer is minted at, so a parked mesh can serve a smaller caller.
|
|
13
|
+
*/
|
|
14
|
+
export const MESH_POOL_MIN_CAPACITY = 64;
|
|
15
|
+
/** Parked meshes per (geometry, material) pair; past it the surplus is released, not hoarded. */
|
|
16
|
+
export const MESH_POOL_MAX_PER_PAIR = 8;
|
|
17
|
+
/** Parked meshes across every pair, so a walk's back-traffic cannot grow without bound. */
|
|
18
|
+
export const MESH_POOL_MAX_HELD = 512;
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* The `update` the pending upload spans belong to; moved once per `WorldCells.update`, which is the
|
|
22
|
+
* frame boundary a render's upload falls between. Module-level like the pool above, because there is
|
|
23
|
+
* one world drawing at a time.
|
|
24
|
+
*/
|
|
25
|
+
let writeEpoch = 0;
|
|
26
|
+
|
|
27
|
+
/** The upload epoch a batch's pending span belongs to; see `advanceWriteEpoch`. */
|
|
28
|
+
export function currentWriteEpoch(): number {
|
|
29
|
+
return writeEpoch;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Starts the next upload epoch, so no batch's pending span outlives the render that consumed it. */
|
|
33
|
+
export function advanceWriteEpoch(): void {
|
|
34
|
+
writeEpoch += 1;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** geometry -> material -> parked meshes, biggest last. */
|
|
38
|
+
const meshPool = new Map<BufferGeometry, Map<Material, InstancedMesh[]>>();
|
|
39
|
+
let meshPoolHeld = 0;
|
|
40
|
+
|
|
41
|
+
/** Capacity a new buffer is minted with: a power of two, so a parked one fits the next cell that asks. */
|
|
42
|
+
function pooledCapacity(capacity: number): number {
|
|
43
|
+
return Math.max(MESH_POOL_MIN_CAPACITY, 2 ** Math.ceil(Math.log2(Math.max(1, capacity))));
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* A mesh drawing `geometry` with `material` that has room for `capacity` instances, from the pool
|
|
48
|
+
* when it has one and freshly minted when it does not.
|
|
49
|
+
*
|
|
50
|
+
* The buffer is always at least a power of two of `MESH_POOL_MIN_CAPACITY` wide: a buffer grown to
|
|
51
|
+
* exactly the count that needed it can only ever serve that count again, whereas a rounded one is
|
|
52
|
+
* the size the next, larger consumer of the same part will ask for.
|
|
53
|
+
*/
|
|
54
|
+
export function pooledMesh(
|
|
55
|
+
geometry: BufferGeometry,
|
|
56
|
+
material: Material,
|
|
57
|
+
capacity: number,
|
|
58
|
+
): InstancedMesh {
|
|
59
|
+
const wanted = pooledCapacity(capacity);
|
|
60
|
+
const forMaterial = meshPool.get(geometry)?.get(material);
|
|
61
|
+
if (forMaterial !== undefined) {
|
|
62
|
+
for (let index = forMaterial.length - 1; index >= 0; index -= 1) {
|
|
63
|
+
const mesh = forMaterial[index] as InstancedMesh;
|
|
64
|
+
if (mesh.instanceMatrix.count < wanted) continue;
|
|
65
|
+
forMaterial.splice(index, 1);
|
|
66
|
+
meshPoolHeld -= 1;
|
|
67
|
+
return mesh;
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
return new InstancedMesh(geometry, material, wanted);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** A mesh that cannot be parked is detached and given up, never just dropped. */
|
|
74
|
+
function releasePooled(mesh: InstancedMesh): void {
|
|
75
|
+
mesh.removeFromParent();
|
|
76
|
+
mesh.dispose();
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Offer a mesh no batch draws any more to the pool. `false` means the pool is full and the caller must
|
|
81
|
+
* let the mesh go; it is never disposed here, because a parked mesh is only a buffer and a uuid, and
|
|
82
|
+
* the geometry and material it points at belong to the refcount path that made it.
|
|
83
|
+
*/
|
|
84
|
+
export function parkMesh(mesh: InstancedMesh): boolean {
|
|
85
|
+
if (meshPoolHeld >= MESH_POOL_MAX_HELD) {
|
|
86
|
+
// Both refusals give the mesh up, and "up" includes letting go of it. Returning `false` with
|
|
87
|
+
// the mesh still parented would leave the old mesh drawing the old records (ghosts) with
|
|
88
|
+
// nothing to clean it up; leaving it detached would leak a buffer, since `InstancedMesh
|
|
89
|
+
// .dispose` frees its own buffer and leaves the geometry and material it shares with every
|
|
90
|
+
// other instance of the part alone.
|
|
91
|
+
releasePooled(mesh);
|
|
92
|
+
return false;
|
|
93
|
+
}
|
|
94
|
+
mesh.removeFromParent();
|
|
95
|
+
mesh.count = 0;
|
|
96
|
+
mesh.visible = false;
|
|
97
|
+
mesh.frustumCulled = false;
|
|
98
|
+
mesh.castShadow = false;
|
|
99
|
+
mesh.receiveShadow = false;
|
|
100
|
+
mesh.instanceMatrix.array.fill(0);
|
|
101
|
+
mesh.instanceMatrix.needsUpdate = true;
|
|
102
|
+
let forGeometry = meshPool.get(mesh.geometry);
|
|
103
|
+
if (forGeometry === undefined) {
|
|
104
|
+
forGeometry = new Map();
|
|
105
|
+
meshPool.set(mesh.geometry, forGeometry);
|
|
106
|
+
}
|
|
107
|
+
let forMaterial = forGeometry.get(mesh.material as Material);
|
|
108
|
+
if (forMaterial === undefined) {
|
|
109
|
+
forMaterial = [];
|
|
110
|
+
forGeometry.set(mesh.material as Material, forMaterial);
|
|
111
|
+
}
|
|
112
|
+
if (forMaterial.length >= MESH_POOL_MAX_PER_PAIR) {
|
|
113
|
+
releasePooled(mesh);
|
|
114
|
+
return false;
|
|
115
|
+
}
|
|
116
|
+
forMaterial.push(mesh);
|
|
117
|
+
meshPoolHeld += 1;
|
|
118
|
+
return true;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* Every parked mesh drawn with one geometry and material, freed. The asset that owns them released
|
|
123
|
+
* them, so no pool may keep them; the pool's held count and its per-pair entry go with them, because
|
|
124
|
+
* a mesh that is gone is not capacity.
|
|
125
|
+
*/
|
|
126
|
+
export function dropPooledFor(geometry: BufferGeometry, material: Material): void {
|
|
127
|
+
const forGeometry = meshPool.get(geometry);
|
|
128
|
+
if (forGeometry === undefined) return;
|
|
129
|
+
const forMaterial = forGeometry.get(material);
|
|
130
|
+
if (forMaterial === undefined) return;
|
|
131
|
+
for (const mesh of forMaterial) {
|
|
132
|
+
releasePooled(mesh);
|
|
133
|
+
meshPoolHeld -= 1;
|
|
134
|
+
}
|
|
135
|
+
forGeometry.delete(material);
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** The pool's meshes, disposed; what a world never gives back, `dispose` takes. */
|
|
139
|
+
export function drainMeshPool(): void {
|
|
140
|
+
for (const forGeometry of meshPool.values())
|
|
141
|
+
for (const forMaterial of forGeometry.values()) for (const mesh of forMaterial) mesh.dispose();
|
|
142
|
+
meshPool.clear();
|
|
143
|
+
meshPoolHeld = 0;
|
|
144
|
+
}
|