@expofp/renderer 3.50.0 → 3.51.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 (60) hide show
  1. package/dist/Renderer.d.ts +2 -2
  2. package/dist/core/batch/BatchedMesh.d.ts +12 -0
  3. package/dist/core/batch/BatchedMesh.js +29 -0
  4. package/dist/core/instanced/InstancedMesh.js +7 -2
  5. package/dist/core/sprites/BatchedSprites.js +2 -2
  6. package/dist/core/sprites/RaycastingSprites.d.ts +9 -1
  7. package/dist/core/sprites/RaycastingSprites.js +23 -3
  8. package/dist/core/sprites/sprite-material.js +5 -6
  9. package/dist/core/text/MemberTexture.js +2 -4
  10. package/dist/events/LayoutDriver.js +17 -1
  11. package/dist/events/layout-targets.js +30 -5
  12. package/dist/events/placement/box.d.ts +14 -0
  13. package/dist/events/placement/box.js +19 -2
  14. package/dist/events/placement/index.d.ts +1 -0
  15. package/dist/events/placement/index.js +1 -0
  16. package/dist/events/placement/pass.js +9 -8
  17. package/dist/events/pointer.d.ts +27 -6
  18. package/dist/events/pointer.js +50 -9
  19. package/dist/index.d.ts +1 -1
  20. package/dist/index.js +2 -2
  21. package/dist/objects/images/Images.js +1 -1
  22. package/dist/objects/lighting/Lighting.d.ts +56 -38
  23. package/dist/objects/lighting/Lighting.js +130 -343
  24. package/dist/objects/lighting/lighting-gui.js +32 -18
  25. package/dist/objects/lighting/studio-environment.d.ts +15 -43
  26. package/dist/objects/lighting/studio-environment.js +18 -126
  27. package/dist/objects/lighting/sun-shadow-map.d.ts +24 -19
  28. package/dist/objects/lighting/sun-shadow-map.js +112 -34
  29. package/dist/objects/materials/ColorMaterial.d.ts +11 -8
  30. package/dist/objects/materials/ColorMaterial.js +33 -11
  31. package/dist/objects/materials/ModelMaterial.js +3 -2
  32. package/dist/objects/materials/OutlineMaterial.d.ts +21 -0
  33. package/dist/objects/materials/OutlineMaterial.js +77 -0
  34. package/dist/objects/materials/TextureMaterial.d.ts +10 -0
  35. package/dist/objects/materials/TextureMaterial.js +13 -2
  36. package/dist/objects/materials/effects/ao/index.d.ts +2 -5
  37. package/dist/objects/materials/effects/ao/index.js +4 -7
  38. package/dist/objects/materials/effects/contact-shadow.d.ts +21 -10
  39. package/dist/objects/materials/effects/contact-shadow.js +60 -16
  40. package/dist/objects/materials/effects/effects-context.d.ts +2 -1
  41. package/dist/objects/materials/effects/effects-context.js +2 -1
  42. package/dist/objects/materials/effects/side-shade.d.ts +40 -0
  43. package/dist/objects/materials/effects/side-shade.js +52 -0
  44. package/dist/objects/materials/effects/sun-shadow.d.ts +5 -21
  45. package/dist/objects/materials/effects/sun-shadow.js +54 -103
  46. package/dist/objects/models/Models.d.ts +3 -2
  47. package/dist/objects/models/Models.js +7 -6
  48. package/dist/objects/models/model-asset.d.ts +51 -21
  49. package/dist/objects/models/model-asset.js +100 -40
  50. package/dist/objects/models/model-container.d.ts +37 -13
  51. package/dist/objects/models/model-container.js +74 -22
  52. package/dist/objects/shapes/Shapes.js +11 -6
  53. package/dist/objects/shapes/shape-container.d.ts +3 -2
  54. package/dist/objects/shapes/shape-container.js +6 -4
  55. package/dist/objects/shapes/shape-geometry.d.ts +16 -4
  56. package/dist/objects/shapes/shape-geometry.js +17 -13
  57. package/dist/types/defs.d.ts +30 -1
  58. package/dist/utils/math.d.ts +14 -0
  59. package/dist/utils/math.js +20 -0
  60. package/package.json +2 -2
@@ -1,17 +1,37 @@
1
1
  import { type AnimationClip, AnimationMixer, Box3, type BufferGeometry, type Group, type Material, Matrix4, type Object3D } from 'three';
2
- /** One drawable piece of a loaded model: everything in it that shares a source material. */
2
+ /**
3
+ * One drawable piece of a loaded model, drawn once per {@link copies | copy} for every def placing
4
+ * the model. It is one of two things:
5
+ *
6
+ * - **Merged**: every mesh the GLB uses once with this material, flattened into one geometry that
7
+ * already sits where the model puts it. One copy, the identity.
8
+ * - **Reused**: one mesh the GLB places several times (several nodes sharing it, or a GPU-instanced
9
+ * node). Its geometry is kept once, in the mesh's own space, with a copy per placement.
10
+ */
3
11
  export interface ModelPart {
4
12
  /**
5
13
  * Identifies the part within its asset, and so keys the mesh drawing it. The material alone will
6
- * not do: parts are bucketed by material **and** merge signature, so one material can yield more
7
- * than one part and two parts can share a `material.uuid`.
14
+ * not do: merged parts are bucketed by material **and** merge signature, and a reused mesh is a
15
+ * part of its own, so two parts can share a `material.uuid`.
8
16
  */
9
17
  readonly id: string;
10
- /** Every mesh in the GLB using {@link material}, flattened and merged into one. */
18
+ /** The geometry each copy draws. */
11
19
  readonly geometry: BufferGeometry;
12
- /** The material the GLB authored for those meshes. Shared; clone before mutating. */
20
+ /** The material the GLB authored for that geometry. Shared; clone before mutating. */
13
21
  readonly material: Material;
14
- /** How the part moves when the GLB animates it. Absent for a part that never moves. */
22
+ /**
23
+ * Where each copy of {@link geometry} sits in the model's own space, in the rest pose. Never
24
+ * empty; a merged part has the identity alone.
25
+ *
26
+ * Kept apart rather than merged because each copy is then its own instance, with its own small
27
+ * bounds: a ray or a frustum that misses a tree skips that tree's triangles, where one geometry
28
+ * spanning the model is tested whole.
29
+ */
30
+ readonly copies: readonly Matrix4[];
31
+ /**
32
+ * How the part moves when the GLB animates it. Absent for a part that never moves. Moves every
33
+ * copy alike: the node's displacement applies outside each copy's matrix.
34
+ */
15
35
  readonly motion?: PartMotion;
16
36
  }
17
37
  /**
@@ -33,10 +53,13 @@ export interface ModelAnimation {
33
53
  export interface ModelAsset {
34
54
  /** Where it was loaded from; also what picks out the defs drawing it. */
35
55
  readonly url: string;
36
- /** One entry per distinct source material, so a whole layer costs one draw call per entry. */
56
+ /**
57
+ * One entry per distinct source material, plus one per mesh the GLB reuses, so a whole layer
58
+ * costs one draw call per entry.
59
+ */
37
60
  readonly parts: readonly ModelPart[];
38
61
  /**
39
- * The union of every baked part's bounds, in the model's own y-up space. `ModelContainer` maps
62
+ * The union of every part's copies' bounds, in the model's own y-up space. `ModelContainer` maps
40
63
  * them into the plan's once, which is the only place the two frames meet. Rest pose for an
41
64
  * animated model, so its fitted scale does not change while it moves.
42
65
  */
@@ -53,18 +76,25 @@ export interface ModelAsset {
53
76
  */
54
77
  export declare function poseAnimation(animation: ModelAnimation, seconds: number): void;
55
78
  /**
56
- * Flattens a loaded glTF scene and merges it down to one geometry per source material.
79
+ * Splits a loaded glTF scene into parts: one per mesh the GLB places more than once, and the rest
80
+ * merged down to one geometry per source material.
81
+ *
82
+ * Every mesh node is first filed under what it draws — its geometry, its material, and the animated
83
+ * node it follows, if any — with its world matrix as one placement. An `EXT_mesh_gpu_instancing`
84
+ * node (an `InstancedMesh`, from gltfpack `-mi`) files one placement per instance; its per-instance
85
+ * colors and custom attributes are dropped with a warning.
57
86
  *
58
- * Per mesh node, its geometry is cloned and transformed by the node's world matrix, so every vertex
59
- * lands relative to the model's root and the node hierarchy is no longer needed — which is what lets
60
- * the merge happen at all. Then it is filed under its material, sub-keyed by {@link mergeSignature},
61
- * because `mergeGeometries` requires its inputs to agree about their attributes.
87
+ * **A geometry placed more than once stays one geometry**, with its placements as the part's
88
+ * {@link ModelPart.copies}, so each draws as its own instance. A venue's trees are the case this is
89
+ * for: a thousand copies of a few small meshes, which merged into a geometry whose bounds covered
90
+ * the venue, so every pointer ray over it tested every tree's triangles.
62
91
  *
63
- * Two shapes compressors emit are unpacked on the way in. An `EXT_mesh_gpu_instancing` node (an
64
- * `InstancedMesh`, from gltfpack `-mi`) is baked once per instance, since the def is our only
65
- * instanced unit; its per-instance colors and custom attributes are dropped with a warning. Quantized
66
- * attributes (`KHR_mesh_quantization`, from gltfpack) are widened to floats first — see
67
- * {@link toFloatGeometry}.
92
+ * **A geometry placed once is merged.** It is cloned and transformed by its placement, so every
93
+ * vertex lands relative to the model's root and the node hierarchy is no longer needed — which is
94
+ * what lets the merge happen at all. Then it is filed under its material, sub-keyed by
95
+ * {@link mergeSignature}, because `mergeGeometries` requires its inputs to agree about their
96
+ * attributes. Quantized attributes (`KHR_mesh_quantization`, from gltfpack) are widened to floats
97
+ * first — see {@link toFloatGeometry}.
68
98
  *
69
99
  * **Nothing here knows about the plan.** The geometry stays in the model's own space, glTF's y-up,
70
100
  * and the mapping onto the plan is a transform the *mesh* carries — see `ModelContainer`. That is
@@ -76,9 +106,9 @@ export declare function poseAnimation(animation: ModelAnimation, seconds: number
76
106
  * `WEBGL_multi_draw` path.
77
107
  *
78
108
  * Animation survives the flattening only where it moves whole nodes. A mesh under an animated node
79
- * is bucketed by that node too, and the part records it as its {@link PartMotion}, so the instance
80
- * can add the node's displacement each frame. Skinned meshes and morph targets are drawn in their
81
- * rest pose, with a warning.
109
+ * is filed by that node too, and the part records it as its {@link PartMotion}, so the instance can
110
+ * add the node's displacement each frame. Skinned meshes and morph targets are drawn in their rest
111
+ * pose, with a warning.
82
112
  * @param scene - The glTF scene to bake.
83
113
  * @param url - Where it came from; carried on the asset, and names the model in diagnostics.
84
114
  * @param clips - The GLB's animations.
@@ -1,4 +1,4 @@
1
- import { AnimationMixer, Box3, BufferAttribute, InstancedMesh, Matrix4, Mesh, PropertyBinding, SkinnedMesh, } from 'three';
1
+ import { AnimationMixer, Box3, BufferAttribute, InstancedBufferAttribute, InstancedMesh, Matrix4, Mesh, PropertyBinding, SkinnedMesh, Vector3, } from 'three';
2
2
  import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js';
3
3
  import { createLogger } from '../../utils/logging';
4
4
  const logger = createLogger('model');
@@ -14,18 +14,25 @@ export function poseAnimation(animation, seconds) {
14
14
  animation.mixer.getRoot().updateMatrixWorld(true);
15
15
  }
16
16
  /**
17
- * Flattens a loaded glTF scene and merges it down to one geometry per source material.
17
+ * Splits a loaded glTF scene into parts: one per mesh the GLB places more than once, and the rest
18
+ * merged down to one geometry per source material.
18
19
  *
19
- * Per mesh node, its geometry is cloned and transformed by the node's world matrix, so every vertex
20
- * lands relative to the model's root and the node hierarchy is no longer needed — which is what lets
21
- * the merge happen at all. Then it is filed under its material, sub-keyed by {@link mergeSignature},
22
- * because `mergeGeometries` requires its inputs to agree about their attributes.
20
+ * Every mesh node is first filed under what it draws — its geometry, its material, and the animated
21
+ * node it follows, if any — with its world matrix as one placement. An `EXT_mesh_gpu_instancing`
22
+ * node (an `InstancedMesh`, from gltfpack `-mi`) files one placement per instance; its per-instance
23
+ * colors and custom attributes are dropped with a warning.
23
24
  *
24
- * Two shapes compressors emit are unpacked on the way in. An `EXT_mesh_gpu_instancing` node (an
25
- * `InstancedMesh`, from gltfpack `-mi`) is baked once per instance, since the def is our only
26
- * instanced unit; its per-instance colors and custom attributes are dropped with a warning. Quantized
27
- * attributes (`KHR_mesh_quantization`, from gltfpack) are widened to floats first — see
28
- * {@link toFloatGeometry}.
25
+ * **A geometry placed more than once stays one geometry**, with its placements as the part's
26
+ * {@link ModelPart.copies}, so each draws as its own instance. A venue's trees are the case this is
27
+ * for: a thousand copies of a few small meshes, which merged into a geometry whose bounds covered
28
+ * the venue, so every pointer ray over it tested every tree's triangles.
29
+ *
30
+ * **A geometry placed once is merged.** It is cloned and transformed by its placement, so every
31
+ * vertex lands relative to the model's root and the node hierarchy is no longer needed — which is
32
+ * what lets the merge happen at all. Then it is filed under its material, sub-keyed by
33
+ * {@link mergeSignature}, because `mergeGeometries` requires its inputs to agree about their
34
+ * attributes. Quantized attributes (`KHR_mesh_quantization`, from gltfpack) are widened to floats
35
+ * first — see {@link toFloatGeometry}.
29
36
  *
30
37
  * **Nothing here knows about the plan.** The geometry stays in the model's own space, glTF's y-up,
31
38
  * and the mapping onto the plan is a transform the *mesh* carries — see `ModelContainer`. That is
@@ -37,19 +44,18 @@ export function poseAnimation(animation, seconds) {
37
44
  * `WEBGL_multi_draw` path.
38
45
  *
39
46
  * Animation survives the flattening only where it moves whole nodes. A mesh under an animated node
40
- * is bucketed by that node too, and the part records it as its {@link PartMotion}, so the instance
41
- * can add the node's displacement each frame. Skinned meshes and morph targets are drawn in their
42
- * rest pose, with a warning.
47
+ * is filed by that node too, and the part records it as its {@link PartMotion}, so the instance can
48
+ * add the node's displacement each frame. Skinned meshes and morph targets are drawn in their rest
49
+ * pose, with a warning.
43
50
  * @param scene - The glTF scene to bake.
44
51
  * @param url - Where it came from; carried on the asset, and names the model in diagnostics.
45
52
  * @param clips - The GLB's animations.
46
53
  * @returns The parsed asset.
47
54
  */
48
55
  export function bakeGltf(scene, url, clips = []) {
49
- const buckets = new Map();
50
- const extents = new Box3();
51
56
  const animated = animatedNodes(scene, clips, url);
52
57
  const motions = new Map();
58
+ const uses = new Map();
53
59
  scene.updateMatrixWorld(true);
54
60
  scene.traverse((node) => {
55
61
  // `instanceof` on a generic class instantiates its parameters as `any`, so the narrowed node is
@@ -72,37 +78,41 @@ export function bakeGltf(scene, url, clips = []) {
72
78
  motion = { node: follows, restInverse: follows.matrixWorld.clone().invert() };
73
79
  motions.set(follows, motion);
74
80
  }
75
- const source = toFloatGeometry(mesh.geometry);
76
- // Per-instance attributes three parked on the shared geometry; each baked copy sheds them.
77
- const dropped = mesh instanceof InstancedMesh
78
- ? Object.keys(source.attributes).filter((name) => name.startsWith('_'))
79
- : [];
80
- const bake = (matrix) => {
81
- const baked = source.clone();
82
- for (const name of dropped)
83
- baked.deleteAttribute(name);
84
- baked.applyMatrix4(matrix);
85
- baked.computeBoundingBox();
86
- if (baked.boundingBox)
87
- extents.union(baked.boundingBox);
88
- const signature = mergeSignature(baked);
89
- const id = `${material.uuid}|${signature}${motion ? `|${motion.node.uuid}` : ''}`;
90
- const bucket = buckets.get(id) ?? { material, signature, motion, geometries: [] };
91
- bucket.geometries.push(baked);
92
- buckets.set(id, bucket);
93
- };
81
+ const key = `${mesh.geometry.uuid}|${material.uuid}${motion ? `|${motion.node.uuid}` : ''}`;
82
+ const use = uses.get(key) ?? { geometry: mesh.geometry, material, motion, placements: [] };
83
+ uses.set(key, use);
94
84
  if (!(mesh instanceof InstancedMesh)) {
95
- bake(mesh.matrixWorld);
85
+ use.placements.push(mesh.matrixWorld.clone());
96
86
  return;
97
87
  }
98
- const ignored = mesh.instanceColor ? [...dropped, '_COLOR_0'] : dropped;
88
+ const ignored = perInstanceAttributes(use.geometry);
89
+ if (mesh.instanceColor)
90
+ ignored.push('_COLOR_0');
99
91
  if (ignored.length > 0) {
100
92
  logger.warn('model %s: ignored per-instance attributes %s on mesh "%s"', url, ignored.join(', '), mesh.name);
101
93
  }
102
94
  for (let i = 0; i < mesh.count; i++) {
103
- bake(_matrix.multiplyMatrices(mesh.matrixWorld, mesh.getMatrixAt(i, _instanceMatrix)));
95
+ use.placements.push(new Matrix4().multiplyMatrices(mesh.matrixWorld, mesh.getMatrixAt(i, _instanceMatrix)));
104
96
  }
105
97
  });
98
+ const extents = new Box3();
99
+ const buckets = new Map();
100
+ const reused = [];
101
+ for (const [key, { geometry, material, motion, placements }] of uses) {
102
+ const source = withoutPerInstanceAttributes(geometry);
103
+ for (const placement of placements)
104
+ expandByPlaced(extents, source, placement);
105
+ if (placements.length > 1) {
106
+ reused.push(withMotion({ id: key, geometry: source, material, copies: placements }, motion));
107
+ continue;
108
+ }
109
+ const baked = toFloatGeometry(source).clone().applyMatrix4(placements[0]);
110
+ const signature = mergeSignature(baked);
111
+ const id = `${material.uuid}|${signature}${motion ? `|${motion.node.uuid}` : ''}`;
112
+ const bucket = buckets.get(id) ?? { material, signature, motion, geometries: [] };
113
+ bucket.geometries.push(baked);
114
+ buckets.set(id, bucket);
115
+ }
106
116
  const parts = [];
107
117
  for (const [id, { material, signature, motion, geometries }] of buckets) {
108
118
  const merged = geometries.length === 1 ? geometries[0] : mergeGeometries(geometries);
@@ -114,8 +124,9 @@ export function bakeGltf(scene, url, clips = []) {
114
124
  logger.warn('model %s: dropped a part, %d geometries would not merge — material "%s" (%s), %s', url, geometries.length, material.name, material.uuid, signature);
115
125
  continue;
116
126
  }
117
- parts.push(motion ? { id, geometry: merged, material, motion } : { id, geometry: merged, material });
127
+ parts.push(withMotion({ id, geometry: merged, material, copies: [new Matrix4()] }, motion));
118
128
  }
129
+ parts.push(...reused);
119
130
  if (motions.size === 0)
120
131
  return { url, parts, extents };
121
132
  const mixer = new AnimationMixer(scene);
@@ -161,6 +172,55 @@ function nearestAnimated(node, animated) {
161
172
  }
162
173
  return null;
163
174
  }
175
+ /**
176
+ * A part, carrying a `motion` key only when it moves.
177
+ * @param part - The part without its motion.
178
+ * @param motion - The node it follows, if any.
179
+ * @returns The part.
180
+ */
181
+ function withMotion(part, motion) {
182
+ return motion ? { ...part, motion } : part;
183
+ }
184
+ /**
185
+ * Grows a box to hold a geometry's vertices where a placement puts them. Vertex by vertex rather
186
+ * than the geometry's bounding box moved, which is larger than what it holds once the placement
187
+ * rotates: the extents set the fitted scale of every def drawing the model.
188
+ * @param box - The box to grow.
189
+ * @param geometry - The geometry.
190
+ * @param placement - Where it sits.
191
+ */
192
+ function expandByPlaced(box, geometry, placement) {
193
+ const position = geometry.getAttribute('position');
194
+ // `fromBufferAttribute` denormalizes, so a quantized geometry measures as its widened copy would.
195
+ for (let i = 0; i < position.count; i++) {
196
+ box.expandByPoint(_vertex.fromBufferAttribute(position, i).applyMatrix4(placement));
197
+ }
198
+ }
199
+ /**
200
+ * The per-instance attributes three's glTF loader parks on a GPU-instanced node's geometry.
201
+ * @param geometry - The geometry.
202
+ * @returns Their names.
203
+ */
204
+ function perInstanceAttributes(geometry) {
205
+ return Object.entries(geometry.attributes)
206
+ .filter(([name, attribute]) => name.startsWith('_') && attribute instanceof InstancedBufferAttribute)
207
+ .map(([name]) => name);
208
+ }
209
+ /**
210
+ * The geometry without its {@link perInstanceAttributes}. A part's per-instance state lives in the
211
+ * mesh's textures, so an instanced attribute left on the geometry is one nothing should read.
212
+ * @param geometry - The geometry; left untouched.
213
+ * @returns The geometry itself, or a copy without them.
214
+ */
215
+ function withoutPerInstanceAttributes(geometry) {
216
+ const dropped = perInstanceAttributes(geometry);
217
+ if (dropped.length === 0)
218
+ return geometry;
219
+ const shed = geometry.clone();
220
+ for (const name of dropped)
221
+ shed.deleteAttribute(name);
222
+ return shed;
223
+ }
164
224
  /**
165
225
  * A stable description of what `mergeGeometries` insists its inputs agree about: whether they are
166
226
  * indexed, and which attributes they carry. Geometries sharing a material but not this are bucketed
@@ -211,5 +271,5 @@ function isPlainFloat(attribute) {
211
271
  attribute.array instanceof Float32Array &&
212
272
  !attribute.normalized);
213
273
  }
214
- const _matrix = new Matrix4();
215
274
  const _instanceMatrix = new Matrix4();
275
+ const _vertex = new Vector3();
@@ -1,9 +1,9 @@
1
1
  import { type Rect } from '@expofp/geometry';
2
2
  import { type Box3, Matrix4 } from 'three';
3
3
  import { type InstancedMeshImpl, type InstancedMeshImplParams } from '../../core/instanced/InstancedMesh';
4
- import { type ModelDef } from '../../types/defs';
4
+ import { type ModelDef, type RenderableDef } from '../../types/defs';
5
5
  import { SlotContainer } from '../containers';
6
- import { type PartMotion } from './model-asset';
6
+ import { type ModelPart, type PartMotion } from './model-asset';
7
7
  /**
8
8
  * The per-instance uniform a model mesh reads its opacity from. The container owns the name: it
9
9
  * declares the schema on bind and writes each slot's value, and hands the name to `ModelMaterial`,
@@ -31,13 +31,19 @@ export type ModelKind = (typeof MODEL_KINDS)[number];
31
31
  */
32
32
  export declare function modelKindOf(def: ModelDef): ModelKind;
33
33
  /**
34
- * One model part's slot bookkeeping: every def in the layer drawing that part gets an instance, so
35
- * twenty copies of a chair are one draw call rather than twenty.
34
+ * One model part's slot bookkeeping: every def in the layer drawing that part gets a slot, so twenty
35
+ * copies of a chair are one draw call rather than twenty.
36
36
  *
37
37
  * Much simpler than a shape container. The geometry is the part's — shared, never per instance — so
38
38
  * there is no geometry cache and no capacity pre-scan, and `InstancedMeshImpl` grows its own buffers,
39
- * so nothing here has to size anything. What is left is a slot per def and the transform each one
40
- * draws with.
39
+ * so nothing here has to size anything. What is left is a slot per def and the transforms it draws
40
+ * with.
41
+ *
42
+ * **A slot is a group of mesh instances**, one per copy of the part (see `ModelPart.copies`): a
43
+ * def placing a model with five hundred trees holds five hundred instances of the tree part. So, as
44
+ * in the text container, a slot is this container's own number and not the mesh's, and every
45
+ * per-instance write goes to each instance in the group. A merged part has one copy, so its group
46
+ * holds one instance.
41
47
  */
42
48
  export declare class ModelContainer extends SlotContainer<null, InstancedMeshImpl, ModelDef> {
43
49
  /** The constructor args R3F builds the mesh from; a frozen snapshot, never mutated. */
@@ -51,16 +57,24 @@ export declare class ModelContainer extends SlotContainer<null, InstancedMeshImp
51
57
  readonly meshMatrix: Matrix4;
52
58
  /** The node the part follows when the GLB animates it; absent for a static part. */
53
59
  readonly motion: PartMotion | undefined;
60
+ /** Where each copy of the part sits in the model; a slot holds one instance per entry. */
61
+ private readonly copies;
54
62
  /** The model's bounds in plan units; every instance is fitted against them. */
55
63
  private readonly extents;
64
+ /** Each slot's mesh instances, index-parallel to {@link copies}, with holes for released slots. */
65
+ private readonly groups;
66
+ private readonly freeSlots;
67
+ /** The slot holding each mesh instance, so a hit, which names an instance, resolves to a def. */
68
+ private readonly slotByInstance;
69
+ private slotCount;
56
70
  /**
57
71
  * Builds the bookkeeping for one model part.
58
72
  * @param extents - The model's own bounds, y-up, as `bakeGltf` left them.
59
- * @param count - How many defs the layer holds for this part, used as the mesh's initial capacity.
73
+ * @param count - How many defs the layer holds for this part; with the copies, sizes the mesh.
60
74
  * @param kind - Which of the layer's batches this is; its material is built for that one alone.
61
- * @param motion - The animated node the part follows, if any.
75
+ * @param part - Where the part's copies sit, and the animated node it follows, if any.
62
76
  */
63
- constructor(extents: Box3, count: number, kind?: ModelKind, motion?: PartMotion);
77
+ constructor(extents: Box3, count: number, kind?: ModelKind, part?: Pick<ModelPart, 'copies' | 'motion'>);
64
78
  /**
65
79
  * Paint order is not implemented for models, so this does nothing.
66
80
  *
@@ -78,14 +92,15 @@ export declare class ModelContainer extends SlotContainer<null, InstancedMeshImp
78
92
  */
79
93
  setPaintOrder(): void;
80
94
  /**
81
- * Writes a def's placement into its slot: the model's extents fitted into `bounds`, and for an
82
- * animated part, moved by its node's current displacement from the rest pose.
95
+ * Writes a def's placement into its slot: each copy where the model puts it, the model's extents
96
+ * fitted into `bounds`, and for an animated part, moved by its node's current displacement from
97
+ * the rest pose.
83
98
  *
84
99
  * The mesh carries {@link PLAN_FROM_GLTF}, so its instances are placed in the model's own space,
85
100
  * while {@link fitToBounds} answers in the plan's. Conjugating moves the placement across — undo
86
101
  * the mesh's map, place, redo it — and is unavoidable: the instance matrix is innermost, so
87
102
  * anything the mesh applies outside it has to be taken back inside.
88
- * @param slot - The instance's slot.
103
+ * @param slot - The def's slot.
89
104
  * @param def - The def supplying the bounds.
90
105
  */
91
106
  place(slot: number, def: ModelDef): void;
@@ -108,10 +123,19 @@ export declare class ModelContainer extends SlotContainer<null, InstancedMeshImp
108
123
  * the def is still in this batch with its new opacity already written. Clamping is what makes the
109
124
  * gap invisible — the model simply stays solid until the batch that can blend it takes over —
110
125
  * without anything having to be fast enough.
111
- * @param slot - The instance's slot.
126
+ * @param slot - The def's slot.
112
127
  * @param def - The def supplying the opacity.
113
128
  */
114
129
  setOpacity(slot: number, def: ModelDef): void;
130
+ setVisibleAt(slot: number, visible: boolean): void;
131
+ /**
132
+ * The mesh reports the instance a ray hit, which is one copy of some def's model, so it resolves
133
+ * to a def through the slot holding it.
134
+ * @param instance - The instance the mesh reported.
135
+ * @returns The def, or `undefined` when no claimed slot holds that instance.
136
+ */
137
+ defAt(instance: number | undefined): RenderableDef | undefined;
138
+ protected writeDim(slot: number, amount: number): void;
115
139
  protected addInstance(): number;
116
140
  protected removeInstance(slot: number): void;
117
141
  }
@@ -27,13 +27,19 @@ export function modelKindOf(def) {
27
27
  return (def.opacity ?? getDefaultModelOpacity()) < 1 ? 'translucent' : 'opaque';
28
28
  }
29
29
  /**
30
- * One model part's slot bookkeeping: every def in the layer drawing that part gets an instance, so
31
- * twenty copies of a chair are one draw call rather than twenty.
30
+ * One model part's slot bookkeeping: every def in the layer drawing that part gets a slot, so twenty
31
+ * copies of a chair are one draw call rather than twenty.
32
32
  *
33
33
  * Much simpler than a shape container. The geometry is the part's — shared, never per instance — so
34
34
  * there is no geometry cache and no capacity pre-scan, and `InstancedMeshImpl` grows its own buffers,
35
- * so nothing here has to size anything. What is left is a slot per def and the transform each one
36
- * draws with.
35
+ * so nothing here has to size anything. What is left is a slot per def and the transforms it draws
36
+ * with.
37
+ *
38
+ * **A slot is a group of mesh instances**, one per copy of the part (see `ModelPart.copies`): a
39
+ * def placing a model with five hundred trees holds five hundred instances of the tree part. So, as
40
+ * in the text container, a slot is this container's own number and not the mesh's, and every
41
+ * per-instance write goes to each instance in the group. A merged part has one copy, so its group
42
+ * holds one instance.
37
43
  */
38
44
  export class ModelContainer extends SlotContainer {
39
45
  /** The constructor args R3F builds the mesh from; a frozen snapshot, never mutated. */
@@ -47,22 +53,31 @@ export class ModelContainer extends SlotContainer {
47
53
  meshMatrix = PLAN_FROM_GLTF;
48
54
  /** The node the part follows when the GLB animates it; absent for a static part. */
49
55
  motion;
56
+ /** Where each copy of the part sits in the model; a slot holds one instance per entry. */
57
+ copies;
50
58
  /** The model's bounds in plan units; every instance is fitted against them. */
51
59
  extents;
60
+ /** Each slot's mesh instances, index-parallel to {@link copies}, with holes for released slots. */
61
+ groups = [];
62
+ freeSlots = [];
63
+ /** The slot holding each mesh instance, so a hit, which names an instance, resolves to a def. */
64
+ slotByInstance = new Map();
65
+ slotCount = 0;
52
66
  /**
53
67
  * Builds the bookkeeping for one model part.
54
68
  * @param extents - The model's own bounds, y-up, as `bakeGltf` left them.
55
- * @param count - How many defs the layer holds for this part, used as the mesh's initial capacity.
69
+ * @param count - How many defs the layer holds for this part; with the copies, sizes the mesh.
56
70
  * @param kind - Which of the layer's batches this is; its material is built for that one alone.
57
- * @param motion - The animated node the part follows, if any.
71
+ * @param part - Where the part's copies sit, and the animated node it follows, if any.
58
72
  */
59
- constructor(extents, count, kind = 'opaque', motion) {
73
+ constructor(extents, count, kind = 'opaque', part = { copies: [new Matrix4()] }) {
60
74
  super({ schema: MODEL_SCHEMA });
61
- this.motion = motion;
75
+ this.motion = part.motion;
76
+ this.copies = part.copies;
62
77
  // Mapped once, here, so that everything below reads plan units — `fitToBounds` included.
63
78
  this.extents = extents.clone().applyMatrix4(PLAN_FROM_GLTF);
64
79
  this.kind = kind;
65
- this.args = [{ capacity: Math.max(count, 1) }];
80
+ this.args = [{ capacity: Math.max(count * part.copies.length, 1) }];
66
81
  }
67
82
  /**
68
83
  * Paint order is not implemented for models, so this does nothing.
@@ -83,23 +98,30 @@ export class ModelContainer extends SlotContainer {
83
98
  // Nothing: the depth buffer orders models, and a layer's parts are separate meshes regardless.
84
99
  }
85
100
  /**
86
- * Writes a def's placement into its slot: the model's extents fitted into `bounds`, and for an
87
- * animated part, moved by its node's current displacement from the rest pose.
101
+ * Writes a def's placement into its slot: each copy where the model puts it, the model's extents
102
+ * fitted into `bounds`, and for an animated part, moved by its node's current displacement from
103
+ * the rest pose.
88
104
  *
89
105
  * The mesh carries {@link PLAN_FROM_GLTF}, so its instances are placed in the model's own space,
90
106
  * while {@link fitToBounds} answers in the plan's. Conjugating moves the placement across — undo
91
107
  * the mesh's map, place, redo it — and is unavoidable: the instance matrix is innermost, so
92
108
  * anything the mesh applies outside it has to be taken back inside.
93
- * @param slot - The instance's slot.
109
+ * @param slot - The def's slot.
94
110
  * @param def - The def supplying the bounds.
95
111
  */
96
112
  place(slot, def) {
97
- this.mesh.setMatrixAt(slot,
98
- // Read right to left: into the plan, placed there, and back out again.
113
+ const group = this.groups[slot];
114
+ if (!group)
115
+ return;
116
+ // Read right to left: the copy into the model, the model's displacement, into the plan, placed
117
+ // there, and back out again.
99
118
  _placement
100
119
  .multiplyMatrices(GLTF_FROM_PLAN, fitToBounds(this.extents, def.bounds))
101
120
  .multiply(PLAN_FROM_GLTF)
102
- .multiply(this.displacement()));
121
+ .multiply(this.displacement());
122
+ for (let copy = 0; copy < group.length; copy++) {
123
+ this.mesh.setMatrixAt(group[copy], _instance.multiplyMatrices(_placement, this.copies[copy]));
124
+ }
103
125
  }
104
126
  /** Re-places every claimed slot, for an animated part after its node moved. */
105
127
  follow() {
@@ -127,25 +149,54 @@ export class ModelContainer extends SlotContainer {
127
149
  * the def is still in this batch with its new opacity already written. Clamping is what makes the
128
150
  * gap invisible — the model simply stays solid until the batch that can blend it takes over —
129
151
  * without anything having to be fast enough.
130
- * @param slot - The instance's slot.
152
+ * @param slot - The def's slot.
131
153
  * @param def - The def supplying the opacity.
132
154
  */
133
155
  setOpacity(slot, def) {
134
156
  // A def without its own opacity defers to the shared default in the shader.
135
157
  const opacity = this.kind === 'translucent' ? (def.opacity ?? USE_DEFAULT_OPACITY) : 1;
136
- this.mesh.setUniformAt(slot, OPACITY_UNIFORM, opacity);
158
+ for (const instance of this.groups[slot] ?? []) {
159
+ this.mesh.setUniformAt(instance, OPACITY_UNIFORM, opacity);
160
+ }
161
+ }
162
+ setVisibleAt(slot, visible) {
163
+ for (const instance of this.groups[slot] ?? [])
164
+ this.mesh.setVisibleAt(instance, visible);
165
+ }
166
+ /**
167
+ * The mesh reports the instance a ray hit, which is one copy of some def's model, so it resolves
168
+ * to a def through the slot holding it.
169
+ * @param instance - The instance the mesh reported.
170
+ * @returns The def, or `undefined` when no claimed slot holds that instance.
171
+ */
172
+ defAt(instance) {
173
+ return super.defAt(instance === undefined ? undefined : this.slotByInstance.get(instance));
174
+ }
175
+ writeDim(slot, amount) {
176
+ for (const instance of this.groups[slot] ?? [])
177
+ super.writeDim(instance, amount);
137
178
  }
138
179
  addInstance() {
180
+ const slot = this.freeSlots.pop() ?? this.slotCount++;
139
181
  // `addInstances` grows the buffers itself if the layer outgrows its sized capacity, so there is
140
- // nothing to pre-scan; the id comes back through the creation callback.
141
- let slot = -1;
142
- this.mesh.addInstances(1, (id) => {
143
- slot = id;
182
+ // nothing to pre-scan; the ids come back through the creation callback, in copy order.
183
+ const group = [];
184
+ this.mesh.addInstances(this.copies.length, (id) => {
185
+ group.push(id);
186
+ this.slotByInstance.set(id, slot);
144
187
  });
188
+ this.groups[slot] = group;
145
189
  return slot;
146
190
  }
147
191
  removeInstance(slot) {
148
- this.mesh.removeInstances(slot);
192
+ const group = this.groups[slot];
193
+ if (!group)
194
+ return;
195
+ this.mesh.removeInstances(...group);
196
+ for (const instance of group)
197
+ this.slotByInstance.delete(instance);
198
+ this.groups[slot] = undefined;
199
+ this.freeSlots.push(slot);
149
200
  }
150
201
  }
151
202
  /**
@@ -227,4 +278,5 @@ const _quaternion = new Quaternion();
227
278
  const _recenter = new Matrix4();
228
279
  const _matrix = new Matrix4();
229
280
  const _placement = new Matrix4();
281
+ const _instance = new Matrix4();
230
282
  const _displacement = new Matrix4();
@@ -3,7 +3,9 @@ import { useState } from 'react';
3
3
  import { BatchedMesh } from '../../core/batch/BatchedMesh';
4
4
  import { defKey, useContainer } from '../containers';
5
5
  import { useOccluder } from '../lighting/occluder';
6
+ import { routeShadow } from '../lighting/sun-shadow-map';
6
7
  import { ColorMaterial } from '../materials/ColorMaterial';
8
+ import { OutlineMaterial } from '../materials/OutlineMaterial';
7
9
  import { SHAPE_KINDS, ShapeContainer, shapeKindOf } from './shape-container';
8
10
  import { ShapeInstance } from './ShapeInstance';
9
11
  /**
@@ -24,7 +26,7 @@ import { ShapeInstance } from './ShapeInstance';
24
26
  export function Shapes(props) {
25
27
  const { defs } = props;
26
28
  // Handed to each batch as a prefix of *its* members rather than apportioned between them: the
27
- // batches are three at most, so a slice can overshoot the scheduler's budget by that factor at
29
+ // batches are four at most, so a slice can overshoot the scheduler's budget by that factor at
28
30
  // worst, and the scheduler measures what a slice actually cost and sizes the next one from it.
29
31
  // Apportioning would cost a walk of the layer's defs per render to find where the prefix falls.
30
32
  const mounted = props.mounted ?? defs.length;
@@ -50,7 +52,7 @@ export function Shapes(props) {
50
52
  // `deleteInstance` and an `addInstance`. That is what an entry in `batches` means: the kind has
51
53
  // held a member at some point, so its batch renders whether or not it holds one now.
52
54
  //
53
- // Mounting all three up front was rejected instead: the tax is the material, not the mesh, and it
55
+ // Mounting all four up front was rejected instead: the tax is the material, not the mesh, and it
54
56
  // would fall on every shape layer of every plan, including the many with no solid content at all.
55
57
  // Stickiness charges it once, and only to a layer that has actually held that kind. An emptied
56
58
  // batch keeps its buffers, since the container never shrinks, and draws nothing — three's
@@ -74,8 +76,8 @@ export function Shapes(props) {
74
76
  }) }));
75
77
  }
76
78
  /**
77
- * Splits a layer's shapes three ways — the flat ones, the opaque volumes, and the translucent
78
- * volumes — by the same {@link shapeKindOf} an instance checks itself against.
79
+ * Splits a layer's shapes four ways — the flat ones, the opaque volumes, the translucent volumes and
80
+ * the outlines — by the same {@link shapeKindOf} an instance checks itself against.
79
81
  * @param defs - The layer's shapes, in paint order.
80
82
  * @param mounted - The batches already mounted, whose entries are carried forward emptied.
81
83
  * @returns The membership and the batches to render, each still in paint order.
@@ -127,7 +129,10 @@ function ShapeBatch(props) {
127
129
  return (_jsxs(_Fragment, { children: [_jsx(BatchedMesh, { args: container.capacity, ref: (mesh) => {
128
130
  container.bind(mesh);
129
131
  occluder(kind === 'solid' ? mesh : null);
132
+ if (mesh)
133
+ routeShadow(mesh, false);
130
134
  }, customSort: container.customSort,
131
- // Solid shapes catch the models' sun shadows.
132
- receiveShadow: kind !== 'planar', renderOrder: renderOrder, children: _jsx(ColorMaterial, { solid: kind !== 'planar', translucent: kind === 'translucent' }) }), defs.slice(0, mounted).map((def) => (_jsx(ShapeInstance, { def: def, container: container }, defKey(def))))] }));
135
+ // Solid shapes catch the sun's shadows, and the opaque ones cast them: a surface you can see
136
+ // through must not cast a full shadow. An outline is a line on the screen, not a surface.
137
+ receiveShadow: kind === 'solid' || kind === 'translucent', castShadow: kind === 'solid', renderOrder: renderOrder, children: kind === 'outline' ? (_jsx(OutlineMaterial, {})) : (_jsx(ColorMaterial, { solid: kind !== 'planar', translucent: kind === 'translucent' })) }), defs.slice(0, mounted).map((def) => (_jsx(ShapeInstance, { def: def, container: container }, defKey(def))))] }));
133
138
  }