@expofp/renderer 3.49.2 → 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 (66) hide show
  1. package/dist/Renderer.d.ts +2 -2
  2. package/dist/core/SquareDataTexture.d.ts +5 -0
  3. package/dist/core/SquareDataTexture.js +6 -0
  4. package/dist/core/batch/BatchedMesh.d.ts +12 -0
  5. package/dist/core/batch/BatchedMesh.js +29 -0
  6. package/dist/core/instanced/InstancedMesh.d.ts +5 -0
  7. package/dist/core/instanced/InstancedMesh.js +12 -0
  8. package/dist/core/sprites/BatchedSprites.js +2 -2
  9. package/dist/core/sprites/RaycastingSprites.d.ts +9 -1
  10. package/dist/core/sprites/RaycastingSprites.js +23 -3
  11. package/dist/core/sprites/sprite-material.js +5 -6
  12. package/dist/core/text/MemberTexture.js +2 -4
  13. package/dist/events/LayoutDriver.js +17 -1
  14. package/dist/events/layout-targets.js +30 -5
  15. package/dist/events/placement/box.d.ts +14 -0
  16. package/dist/events/placement/box.js +19 -2
  17. package/dist/events/placement/index.d.ts +1 -0
  18. package/dist/events/placement/index.js +1 -0
  19. package/dist/events/placement/pass.js +9 -8
  20. package/dist/events/pointer.d.ts +27 -6
  21. package/dist/events/pointer.js +50 -9
  22. package/dist/index.d.ts +1 -1
  23. package/dist/index.js +2 -2
  24. package/dist/objects/containers/SlotContainer.d.ts +5 -0
  25. package/dist/objects/containers/SlotContainer.js +7 -0
  26. package/dist/objects/images/Images.js +1 -1
  27. package/dist/objects/lighting/Lighting.d.ts +56 -38
  28. package/dist/objects/lighting/Lighting.js +136 -344
  29. package/dist/objects/lighting/lighting-gui.js +32 -18
  30. package/dist/objects/lighting/studio-environment.d.ts +15 -43
  31. package/dist/objects/lighting/studio-environment.js +18 -126
  32. package/dist/objects/lighting/sun-shadow-map.d.ts +39 -15
  33. package/dist/objects/lighting/sun-shadow-map.js +163 -26
  34. package/dist/objects/materials/ColorMaterial.d.ts +11 -8
  35. package/dist/objects/materials/ColorMaterial.js +33 -11
  36. package/dist/objects/materials/ModelMaterial.js +3 -2
  37. package/dist/objects/materials/OutlineMaterial.d.ts +21 -0
  38. package/dist/objects/materials/OutlineMaterial.js +77 -0
  39. package/dist/objects/materials/TextureMaterial.d.ts +10 -0
  40. package/dist/objects/materials/TextureMaterial.js +13 -2
  41. package/dist/objects/materials/effects/ao/index.d.ts +2 -5
  42. package/dist/objects/materials/effects/ao/index.js +4 -7
  43. package/dist/objects/materials/effects/contact-shadow.d.ts +21 -10
  44. package/dist/objects/materials/effects/contact-shadow.js +60 -16
  45. package/dist/objects/materials/effects/effects-context.d.ts +2 -1
  46. package/dist/objects/materials/effects/effects-context.js +2 -1
  47. package/dist/objects/materials/effects/side-shade.d.ts +40 -0
  48. package/dist/objects/materials/effects/side-shade.js +52 -0
  49. package/dist/objects/materials/effects/sun-shadow.d.ts +5 -21
  50. package/dist/objects/materials/effects/sun-shadow.js +56 -89
  51. package/dist/objects/models/Models.d.ts +3 -2
  52. package/dist/objects/models/Models.js +46 -8
  53. package/dist/objects/models/gltf-cache.js +1 -1
  54. package/dist/objects/models/model-asset.d.ts +84 -20
  55. package/dist/objects/models/model-asset.js +171 -40
  56. package/dist/objects/models/model-container.d.ts +46 -10
  57. package/dist/objects/models/model-container.js +92 -19
  58. package/dist/objects/shapes/Shapes.js +11 -6
  59. package/dist/objects/shapes/shape-container.d.ts +3 -2
  60. package/dist/objects/shapes/shape-container.js +6 -4
  61. package/dist/objects/shapes/shape-geometry.d.ts +16 -4
  62. package/dist/objects/shapes/shape-geometry.js +17 -13
  63. package/dist/types/defs.d.ts +30 -1
  64. package/dist/utils/math.d.ts +14 -0
  65. package/dist/utils/math.js +20 -0
  66. package/package.json +2 -2
@@ -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. */
@@ -45,20 +51,33 @@ export class ModelContainer extends SlotContainer {
45
51
  * requires and {@link place}'s plan-space answers land where they say. See {@link PLAN_FROM_GLTF}.
46
52
  */
47
53
  meshMatrix = PLAN_FROM_GLTF;
54
+ /** The node the part follows when the GLB animates it; absent for a static part. */
55
+ motion;
56
+ /** Where each copy of the part sits in the model; a slot holds one instance per entry. */
57
+ copies;
48
58
  /** The model's bounds in plan units; every instance is fitted against them. */
49
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;
50
66
  /**
51
67
  * Builds the bookkeeping for one model part.
52
68
  * @param extents - The model's own bounds, y-up, as `bakeGltf` left them.
53
- * @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.
54
70
  * @param kind - Which of the layer's batches this is; its material is built for that one alone.
71
+ * @param part - Where the part's copies sit, and the animated node it follows, if any.
55
72
  */
56
- constructor(extents, count, kind = 'opaque') {
73
+ constructor(extents, count, kind = 'opaque', part = { copies: [new Matrix4()] }) {
57
74
  super({ schema: MODEL_SCHEMA });
75
+ this.motion = part.motion;
76
+ this.copies = part.copies;
58
77
  // Mapped once, here, so that everything below reads plan units — `fitToBounds` included.
59
78
  this.extents = extents.clone().applyMatrix4(PLAN_FROM_GLTF);
60
79
  this.kind = kind;
61
- this.args = [{ capacity: Math.max(count, 1) }];
80
+ this.args = [{ capacity: Math.max(count * part.copies.length, 1) }];
62
81
  }
63
82
  /**
64
83
  * Paint order is not implemented for models, so this does nothing.
@@ -79,21 +98,44 @@ export class ModelContainer extends SlotContainer {
79
98
  // Nothing: the depth buffer orders models, and a layer's parts are separate meshes regardless.
80
99
  }
81
100
  /**
82
- * Writes a def's placement into its slot: the model's extents fitted into `bounds`.
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.
83
104
  *
84
105
  * The mesh carries {@link PLAN_FROM_GLTF}, so its instances are placed in the model's own space,
85
106
  * while {@link fitToBounds} answers in the plan's. Conjugating moves the placement across — undo
86
107
  * the mesh's map, place, redo it — and is unavoidable: the instance matrix is innermost, so
87
108
  * anything the mesh applies outside it has to be taken back inside.
88
- * @param slot - The instance's slot.
109
+ * @param slot - The def's slot.
89
110
  * @param def - The def supplying the bounds.
90
111
  */
91
112
  place(slot, def) {
92
- this.mesh.setMatrixAt(slot,
93
- // 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.
94
118
  _placement
95
119
  .multiplyMatrices(GLTF_FROM_PLAN, fitToBounds(this.extents, def.bounds))
96
- .multiply(PLAN_FROM_GLTF));
120
+ .multiply(PLAN_FROM_GLTF)
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
+ }
125
+ }
126
+ /** Re-places every claimed slot, for an animated part after its node moved. */
127
+ follow() {
128
+ for (const [slot, def] of this.claims())
129
+ this.place(slot, def);
130
+ }
131
+ /**
132
+ * How far the followed node has moved from the pose the geometry was baked in, in glTF space.
133
+ * @returns The shared scratch matrix: the identity for a static part.
134
+ */
135
+ displacement() {
136
+ if (!this.motion)
137
+ return _displacement.identity();
138
+ return _displacement.multiplyMatrices(this.motion.node.matrixWorld, this.motion.restInverse);
97
139
  }
98
140
  /**
99
141
  * Writes a def's opacity into its slot — **clamped to opaque unless this batch blends**.
@@ -107,25 +149,54 @@ export class ModelContainer extends SlotContainer {
107
149
  * the def is still in this batch with its new opacity already written. Clamping is what makes the
108
150
  * gap invisible — the model simply stays solid until the batch that can blend it takes over —
109
151
  * without anything having to be fast enough.
110
- * @param slot - The instance's slot.
152
+ * @param slot - The def's slot.
111
153
  * @param def - The def supplying the opacity.
112
154
  */
113
155
  setOpacity(slot, def) {
114
156
  // A def without its own opacity defers to the shared default in the shader.
115
157
  const opacity = this.kind === 'translucent' ? (def.opacity ?? USE_DEFAULT_OPACITY) : 1;
116
- 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);
117
178
  }
118
179
  addInstance() {
180
+ const slot = this.freeSlots.pop() ?? this.slotCount++;
119
181
  // `addInstances` grows the buffers itself if the layer outgrows its sized capacity, so there is
120
- // nothing to pre-scan; the id comes back through the creation callback.
121
- let slot = -1;
122
- this.mesh.addInstances(1, (id) => {
123
- 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);
124
187
  });
188
+ this.groups[slot] = group;
125
189
  return slot;
126
190
  }
127
191
  removeInstance(slot) {
128
- 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);
129
200
  }
130
201
  }
131
202
  /**
@@ -207,3 +278,5 @@ const _quaternion = new Quaternion();
207
278
  const _recenter = new Matrix4();
208
279
  const _matrix = new Matrix4();
209
280
  const _placement = new Matrix4();
281
+ const _instance = new Matrix4();
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
  }
@@ -10,13 +10,14 @@ import { SlotContainer } from '../containers';
10
10
  * Solids draw after the flat shapes, so a volume occludes the flat content of its own layer rather
11
11
  * than being painted over by it — the same rule that governs whole layers, applied within one.
12
12
  */
13
- export declare const SHAPE_KINDS: readonly ['planar', 'solid', 'translucent'];
13
+ export declare const SHAPE_KINDS: readonly ['planar', 'solid', 'translucent', 'outline'];
14
14
  /**
15
- * Which of a layer's three shape batches a def belongs in, and what that batch is for:
15
+ * Which of a layer's shape batches a def belongs in, and what that batch is for:
16
16
  *
17
17
  * - `planar` — flat content: unlit, no depth writes, placed by draw order alone.
18
18
  * - `solid` — opaque volumes: lit and depth-writing, drawn in the ordered stream.
19
19
  * - `translucent` — the same volumes, drawn in three's transparent pass.
20
+ * - `outline` — volumes drawn as their silhouette alone, see {@link ShapeDef.outline}.
20
21
  *
21
22
  * One value rather than the `solid`/`translucent` pair it replaces. The pair could express a
22
23
  * translucent-but-flat batch, which nothing partitions for and no material describes, and it split
@@ -9,7 +9,7 @@ import { shapeGeometry } from './shape-geometry';
9
9
  * Solids draw after the flat shapes, so a volume occludes the flat content of its own layer rather
10
10
  * than being painted over by it — the same rule that governs whole layers, applied within one.
11
11
  */
12
- export const SHAPE_KINDS = ['planar', 'solid', 'translucent'];
12
+ export const SHAPE_KINDS = ['planar', 'solid', 'translucent', 'outline'];
13
13
  /**
14
14
  * The batch a def belongs in.
15
15
  *
@@ -44,6 +44,8 @@ export const SHAPE_KINDS = ['planar', 'solid', 'translucent'];
44
44
  export function shapeKindOf(def) {
45
45
  if (!isMesh(def.shape) || def.shape.isPlanar)
46
46
  return 'planar';
47
+ if (def.outline)
48
+ return 'outline';
47
49
  return isTranslucentColor(def.color) ? 'translucent' : 'solid';
48
50
  }
49
51
  /**
@@ -119,9 +121,9 @@ export class ShapeContainer extends SlotContainer {
119
121
  * @returns The geometry, built on first use.
120
122
  */
121
123
  geometryFor(shape) {
122
- // Both volume kinds share one layout, which is what lets the cache serve a def crossing between
123
- // them without rebuilding anything.
124
- return shapeGeometry(shape, this.kind !== 'planar');
124
+ // Both filled volume kinds share one layout, which is what lets the cache serve a def crossing
125
+ // between them without rebuilding anything.
126
+ return shapeGeometry(shape, this.kind === 'translucent' ? 'solid' : this.kind);
125
127
  }
126
128
  /**
127
129
  * Declares the membership this container is about to hold, setting the size the next growth jumps
@@ -1,5 +1,7 @@
1
1
  import { type Shape } from '@expofp/geometry';
2
2
  import { BufferGeometry } from 'three';
3
+ /** The layouts a shape's template geometry comes in, one per kind of container that draws it. */
4
+ export type ShapeLayout = keyof ShapeLayouts;
3
5
  /**
4
6
  * The template geometry a shape draws with, in the layout its batch locks itself into. Boxes and
5
7
  * rects share one unit plane and are placed by their instance transform; meshes and polygons carry
@@ -17,11 +19,21 @@ import { BufferGeometry } from 'three';
17
19
  * ones until their shape is collected, the two planes for the life of the process, which is a few
18
20
  * hundred bytes of vertex data against a plane rebuilt per shape layer of every plan.
19
21
  * @param shape - The shape to resolve.
20
- * @param solid - Whether the container drawing it holds volumes. A batched mesh mirrors its first
22
+ * @param layout - The layout of the container drawing it. A batched mesh mirrors its first
21
23
  * geometry's attributes *and* its index-ness and three rejects any later geometry that disagrees,
22
- * so the container's own flag decides the layout rather than anything derived here — a container
23
- * holding a shape it should not is then caught by `addGeometry` rather than served quietly.
24
+ * so the container's own layout decides rather than anything derived here — a container holding
25
+ * a shape it should not is then caught by `addGeometry` rather than served quietly.
24
26
  * @returns The geometry, built on first use.
25
27
  */
26
- export declare function shapeGeometry(shape: Shape, solid: boolean): BufferGeometry;
28
+ export declare function shapeGeometry(shape: Shape, layout: ShapeLayout): BufferGeometry;
29
+ /** The layouts one shape has been built in, each filled on first use. */
30
+ interface ShapeLayouts {
31
+ /** Indexed and position-only, for the unlit material a flat batch draws with. */
32
+ planar?: BufferGeometry;
33
+ /** Non-indexed with creased normals, for the lit material a volume batch draws with. */
34
+ solid?: BufferGeometry;
35
+ /** Non-indexed with smooth normals, for the material an outline batch draws with. */
36
+ outline?: BufferGeometry;
37
+ }
38
+ export {};
27
39
  //# sourceMappingURL=shape-geometry.d.ts.map
@@ -18,22 +18,22 @@ import { toCreasedNormals } from 'three/examples/jsm/utils/BufferGeometryUtils.j
18
18
  * ones until their shape is collected, the two planes for the life of the process, which is a few
19
19
  * hundred bytes of vertex data against a plane rebuilt per shape layer of every plan.
20
20
  * @param shape - The shape to resolve.
21
- * @param solid - Whether the container drawing it holds volumes. A batched mesh mirrors its first
21
+ * @param layout - The layout of the container drawing it. A batched mesh mirrors its first
22
22
  * geometry's attributes *and* its index-ness and three rejects any later geometry that disagrees,
23
- * so the container's own flag decides the layout rather than anything derived here — a container
24
- * holding a shape it should not is then caught by `addGeometry` rather than served quietly.
23
+ * so the container's own layout decides rather than anything derived here — a container holding
24
+ * a shape it should not is then caught by `addGeometry` rather than served quietly.
25
25
  * @returns The geometry, built on first use.
26
26
  */
27
- export function shapeGeometry(shape, solid) {
28
- const layout = solid ? 'solid' : 'planar';
29
- if (isBox(shape) || isRect(shape))
30
- return (planes[layout] ??= makePlaneGeometry(solid));
27
+ export function shapeGeometry(shape, layout) {
28
+ if (isBox(shape) || isRect(shape)) {
29
+ return (planes[layout] ??= makePlaneGeometry(layout !== 'planar'));
30
+ }
31
31
  let layouts = shapeGeometries.get(shape);
32
32
  if (!layouts) {
33
33
  layouts = {};
34
34
  shapeGeometries.set(shape, layouts);
35
35
  }
36
- return (layouts[layout] ??= makeMeshGeometry(shape, solid));
36
+ return (layouts[layout] ??= makeMeshGeometry(shape, layout));
37
37
  }
38
38
  /**
39
39
  * The unit plane every box and rect draws with, scaled and placed by its instance transform.
@@ -52,25 +52,29 @@ function makePlaneGeometry(solid) {
52
52
  }
53
53
  /**
54
54
  * Builds geometry from a mesh-like shape: indexed and position-only for a planar container,
55
- * non-indexed with creased normals for a solid one.
55
+ * non-indexed with creased normals for a solid one, and non-indexed with smooth normals for an
56
+ * outline.
56
57
  *
57
58
  * The creasing is what makes an extruded shape read as architecture rather than as a smoothed blob —
58
59
  * faces meeting at more than 30° keep a hard edge, so walls stay flat and corners stay sharp.
60
+ *
61
+ * An outline pushes each vertex out along its normal, so it wants every corner's normal shared by
62
+ * the faces meeting there: a hard edge would push its two faces apart and open a notch at it.
59
63
  * @param mesh - The shape supplying vertices and triangle indices.
60
- * @param solid - Whether the container draws volumes.
64
+ * @param layout - The container's layout.
61
65
  * @returns The geometry.
62
66
  */
63
- function makeMeshGeometry(mesh, solid) {
67
+ function makeMeshGeometry(mesh, layout) {
64
68
  const geometry = new BufferGeometry()
65
69
  .setFromPoints(mesh.vertices)
66
70
  .setIndex(mesh.indices.flat());
67
- if (!solid)
71
+ if (layout === 'planar')
68
72
  return geometry;
69
73
  // Not chained: `computeVertexNormals` returns void rather than `this`, and `toCreasedNormals`
70
74
  // needs the seed normals it writes.
71
75
  const expanded = geometry.toNonIndexed();
72
76
  expanded.computeVertexNormals();
73
- return toCreasedNormals(expanded, CREASE_ANGLE);
77
+ return toCreasedNormals(expanded, layout === 'solid' ? CREASE_ANGLE : Math.PI);
74
78
  }
75
79
  /**
76
80
  * Template geometry per mesh-like shape, weak so it is collected with the shape that keyed it.
@@ -67,8 +67,12 @@ export interface ClusterOptions {
67
67
  * The size of the marker you draw for a cluster. Any def or cluster that this marker would
68
68
  * cover joins the cluster. Without it, the marker takes the size of the cluster's first member.
69
69
  * When several clustering layers share a scope, the first layer's marker is used.
70
+ *
71
+ * A function sizes each cluster's marker from what it holds, for a marker that grows with its
72
+ * count or changes shape with its members. The pass calls it each time it measures a cluster,
73
+ * which is again after every def the cluster absorbs, so keep it cheap.
70
74
  */
71
- marker?: ClusterMarker;
75
+ marker?: ClusterMarker | ((members: readonly (ImageDef | TextDef)[], unitCount: number) => ClusterMarker);
72
76
  /**
73
77
  * Receives the full current set of clusters whenever it changes. A layer that loses all its
74
78
  * clusters receives an empty array once.
@@ -104,6 +108,11 @@ export interface Cluster {
104
108
  readonly y: number;
105
109
  /** The greatest elevation of its members, in plan units. */
106
110
  readonly elevation: number;
111
+ /**
112
+ * The defs that stand behind the cluster, seed first. A fresh array on each report, so a caller
113
+ * may keep it.
114
+ */
115
+ readonly members: readonly (ImageDef | TextDef)[];
107
116
  }
108
117
  /**
109
118
  * How a def competes for room on screen.
@@ -136,6 +145,20 @@ export interface PlacementOptions {
136
145
  group?: string;
137
146
  /** CSS pixels added around the tested box: one value, or `[horizontal, vertical]`. */
138
147
  padding?: number | [number, number];
148
+ /**
149
+ * The rect the pass tests, apart from the one the def is drawn at: in the units of the def's own
150
+ * `bounds`, its center standing on {@link origin}. Its center is also the def's anchor in a
151
+ * cluster. Without it, the pass tests `bounds`.
152
+ *
153
+ * With it, `bounds` and the def's own `origin` are drawing alone, so an animation can write them
154
+ * every frame: an `update()` that changes only them owes no pass and moves no cluster.
155
+ */
156
+ bounds?: Rect;
157
+ /**
158
+ * The point of {@link bounds} that its center names, as in {@link ImageDef.origin}. Defaults to
159
+ * the def's own origin.
160
+ */
161
+ origin?: [number, number];
139
162
  /** How the def competes. Defaults to `never`. */
140
163
  overlap?: OverlapMode;
141
164
  }
@@ -162,6 +185,12 @@ export interface ShapeDef extends SharedDef {
162
185
  shape: Shape;
163
186
  /** The shape's color. */
164
187
  color: ColorInput;
188
+ /**
189
+ * Draws a solid shape as its outline alone: a line a few screen pixels wide around its silhouette,
190
+ * in {@link color}, hidden wherever nearer content covers it. A flat shape has no silhouette and
191
+ * ignores this.
192
+ */
193
+ outline?: boolean;
165
194
  }
166
195
  /** Image definition. */
167
196
  export interface ImageDef extends ScreenSpaceDef {
@@ -49,4 +49,18 @@ export declare function axisLength(matrix: Matrix4, axis: number): number;
49
49
  * @returns The distance in world units, or `0` for a camera that never meets the plane ahead of it.
50
50
  */
51
51
  export declare function aimDepth(camera: Camera, planToWorld: Matrix4): number;
52
+ /**
53
+ * The depth a screen-space def's plan-unit size is exact at: {@link aimDepth} under a projection
54
+ * that divides by depth, and `0`, which turns the depth correction off, under one that does not.
55
+ *
56
+ * Read off the projection matrix rather than the camera's `isPerspectiveCamera` brand or an exact
57
+ * `-1` in its w row. An external host hands its camera a projection with its own unit conversion
58
+ * folded in (MapLibre's w row reads about `-1e8`), on a plain `Camera`, and that projection divides
59
+ * by depth all the same. A perspective w row takes view z and drops the constant term; an
60
+ * orthographic one is the constant `1` alone.
61
+ * @param camera - The camera this draw uses.
62
+ * @param planToWorld - The batch's world matrix.
63
+ * @returns The depth in world units, or `0` for no correction.
64
+ */
65
+ export declare function referenceDepth(camera: Camera, planToWorld: Matrix4): number;
52
66
  //# sourceMappingURL=math.d.ts.map
@@ -69,6 +69,26 @@ export function aimDepth(camera, planToWorld) {
69
69
  // Behind the camera is no measurement, so the shader keeps its plan-unit sizing instead.
70
70
  return depth > 0 ? depth : 0;
71
71
  }
72
+ /**
73
+ * The depth a screen-space def's plan-unit size is exact at: {@link aimDepth} under a projection
74
+ * that divides by depth, and `0`, which turns the depth correction off, under one that does not.
75
+ *
76
+ * Read off the projection matrix rather than the camera's `isPerspectiveCamera` brand or an exact
77
+ * `-1` in its w row. An external host hands its camera a projection with its own unit conversion
78
+ * folded in (MapLibre's w row reads about `-1e8`), on a plain `Camera`, and that projection divides
79
+ * by depth all the same. A perspective w row takes view z and drops the constant term; an
80
+ * orthographic one is the constant `1` alone.
81
+ * @param camera - The camera this draw uses.
82
+ * @param planToWorld - The batch's world matrix.
83
+ * @returns The depth in world units, or `0` for no correction.
84
+ */
85
+ export function referenceDepth(camera, planToWorld) {
86
+ const elements = camera.projectionMatrix.elements;
87
+ // Column-major: element 11 is w's view-z coefficient, element 15 its constant term.
88
+ if (!(Math.abs(elements[11]) > Math.abs(elements[15])))
89
+ return 0;
90
+ return aimDepth(camera, planToWorld);
91
+ }
72
92
  // Scratch for aimDepth, filled and consumed within one call.
73
93
  const _direction = new Vector3();
74
94
  const _normal = new Vector3();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@expofp/renderer",
3
- "version": "3.49.2",
3
+ "version": "3.51.0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "https://github.com/expofp/efp-app.git",
@@ -42,7 +42,7 @@
42
42
  "troika-three-text": "^0.52.5",
43
43
  "tslib": "^2.3.0",
44
44
  "webgl-memory": "^1.1.3",
45
- "@expofp/geometry": "3.49.2"
45
+ "@expofp/geometry": "3.51.0"
46
46
  },
47
47
  "devDependencies": {
48
48
  "@react-three/test-renderer": "^9.1.0",