@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
@@ -62,8 +62,8 @@ export interface RendererProps extends HTMLAttributes<HTMLDivElement>, CameraPro
62
62
  */
63
63
  controls?: ControlsConfig;
64
64
  /**
65
- * The scene's lighting, and the darkening that rides with it: the rig's contrast and three
66
- * colors, and a `shadow` object holding the shade both darkening terms blend toward and each
65
+ * The scene's lighting, and the darkening that rides with it: the sun's share of a facing
66
+ * surface, the studio's turn, and a `shadow` object holding the shade both darkening terms blend toward and each
67
67
  * term's own numbers. See {@link LightingProps}.
68
68
  *
69
69
  * Every value is optional and every omitted one keeps the design's own default, so a caller sets
@@ -106,6 +106,11 @@ export declare class SquareDataTexture extends DataTexture {
106
106
  * @default Infinity
107
107
  */
108
108
  maxUpdateCalls: number;
109
+ /**
110
+ * Counts every write, partial ones included, so a reader can tell the data changed. `version`
111
+ * cannot: it moves only for a full upload.
112
+ */
113
+ revision: number;
109
114
  /** Format/type conversion helper, built on first upload. */
110
115
  protected _utils: WebGLUtils | null;
111
116
  /** Whether any row has been marked since the last upload. */
@@ -83,6 +83,11 @@ export class SquareDataTexture extends DataTexture {
83
83
  * @default Infinity
84
84
  */
85
85
  maxUpdateCalls = Infinity;
86
+ /**
87
+ * Counts every write, partial ones included, so a reader can tell the data changed. `version`
88
+ * cannot: it moves only for a full upload.
89
+ */
90
+ revision = 0;
86
91
  /** Format/type conversion helper, built on first upload. */
87
92
  _utils = null;
88
93
  /** Whether any row has been marked since the last upload. */
@@ -159,6 +164,7 @@ export class SquareDataTexture extends DataTexture {
159
164
  */
160
165
  enqueueUpdate(index) {
161
166
  this._needsUpdate = true;
167
+ this.revision++;
162
168
  if (!this.partialUpdate)
163
169
  return;
164
170
  const elementsPerRow = this.image.width / this._pixelsPerInstance;
@@ -20,6 +20,16 @@ import { type UniformValue, type UniformValueObj } from '../SquareDataTexture';
20
20
  * cached bounds, so callers cannot forget; three's frustum test recomputes a null one on demand.
21
21
  */
22
22
  export declare class BatchedMeshImpl extends BatchedMeshBase {
23
+ /**
24
+ * Counts every write that can change the shadow this mesh casts: an instance added, deleted,
25
+ * moved, shown or hidden. The sun's shadow map is redrawn when it moves.
26
+ */
27
+ shadowVersion: number;
28
+ /**
29
+ * Whether the mesh draws into the shadow map a given shadow camera renders. `null` draws into
30
+ * every map. A declined pass draws nothing.
31
+ */
32
+ shadowFilter: ((shadowCamera: Camera) => boolean) | null;
23
33
  /** Per-instance uniform store, shared with {@link InstancedMeshImpl}. */
24
34
  private readonly uniforms;
25
35
  /** The material whose `onBeforeCompile` is already wrapped, so it is wrapped exactly once. */
@@ -47,9 +57,11 @@ export declare class BatchedMeshImpl extends BatchedMeshBase {
47
57
  setUniformAt(id: number, name: string, value: UniformValue): void;
48
58
  raycast(raycaster: Raycaster, intersects: Intersection[]): void;
49
59
  onBeforeRender(renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group): void;
60
+ onBeforeShadow(renderer: WebGLRenderer, scene: Scene, camera: Camera, shadowCamera: Camera, geometry: BufferGeometry, depthMaterial: Material, group: Group): void;
50
61
  addInstance(geometryId: number): number;
51
62
  deleteInstance(instanceId: number): this;
52
63
  setMatrixAt(instanceId: number, matrix: Matrix4): this;
64
+ setVisibleAt(instanceId: number, visible: boolean): this;
53
65
  setInstanceCount(maxInstanceCount: number): void;
54
66
  dispose(): void;
55
67
  /**
@@ -21,6 +21,16 @@ import { openMain } from '../shader-source';
21
21
  * cached bounds, so callers cannot forget; three's frustum test recomputes a null one on demand.
22
22
  */
23
23
  export class BatchedMeshImpl extends BatchedMeshBase {
24
+ /**
25
+ * Counts every write that can change the shadow this mesh casts: an instance added, deleted,
26
+ * moved, shown or hidden. The sun's shadow map is redrawn when it moves.
27
+ */
28
+ shadowVersion = 0;
29
+ /**
30
+ * Whether the mesh draws into the shadow map a given shadow camera renders. `null` draws into
31
+ * every map. A declined pass draws nothing.
32
+ */
33
+ shadowFilter = null;
24
34
  /** Per-instance uniform store, shared with {@link InstancedMeshImpl}. */
25
35
  uniforms = new InstanceUniforms();
26
36
  /** The material whose `onBeforeCompile` is already wrapped, so it is wrapped exactly once. */
@@ -78,6 +88,15 @@ export class BatchedMeshImpl extends BatchedMeshBase {
78
88
  this.patchMaterial();
79
89
  this.uniforms.texture.update(renderer);
80
90
  }
91
+ onBeforeShadow(renderer, scene, camera, shadowCamera, geometry, depthMaterial, group) {
92
+ if (this.shadowFilter && !this.shadowFilter(shadowCamera)) {
93
+ // three draws the count its last cull left, in a field its types omit. Per-object culling
94
+ // counts again for the next pass, so a declined one skips its own cull and draws nothing.
95
+ this._multiDrawCount = 0;
96
+ return;
97
+ }
98
+ super.onBeforeShadow(renderer, scene, camera, shadowCamera, geometry, depthMaterial, group);
99
+ }
81
100
  addInstance(geometryId) {
82
101
  const instanceId = super.addInstance(geometryId);
83
102
  this.invalidateBounds();
@@ -93,6 +112,15 @@ export class BatchedMeshImpl extends BatchedMeshBase {
93
112
  this.invalidateBounds();
94
113
  return this;
95
114
  }
115
+ setVisibleAt(instanceId, visible) {
116
+ // Every def sync writes its visibility, so an unchanged write is the common case. Counting it
117
+ // would redraw the sun's shadow map on every frame something animates.
118
+ if (this.getVisibleAt(instanceId) === visible)
119
+ return this;
120
+ super.setVisibleAt(instanceId, visible);
121
+ this.shadowVersion++;
122
+ return this;
123
+ }
96
124
  setInstanceCount(maxInstanceCount) {
97
125
  super.setInstanceCount(maxInstanceCount);
98
126
  // The uniform texture is sized per instance, so it has to grow with the mesh.
@@ -109,6 +137,7 @@ export class BatchedMeshImpl extends BatchedMeshBase {
109
137
  invalidateBounds() {
110
138
  this.boundingBox = null;
111
139
  this.boundingSphere = null;
140
+ this.shadowVersion++;
112
141
  }
113
142
  /**
114
143
  * Wraps the current material's `onBeforeCompile` so compiled programs can read the uniform
@@ -79,6 +79,11 @@ export declare class InstancedMeshImpl extends Mesh<BufferGeometry, Material | M
79
79
  perObjectFrustumCulled: boolean;
80
80
  /** Whether instances are depth-sorted (via {@link customSort}) before drawing. */
81
81
  sortObjects: boolean;
82
+ /**
83
+ * Whether the mesh draws into the shadow map a given shadow camera renders. `null` draws into
84
+ * every map. A declined pass draws zero instances.
85
+ */
86
+ shadowFilter: ((shadowCamera: Camera) => boolean) | null;
82
87
  /** Bounding box enclosing every instance; nulled on mutation and recomputed on demand. */
83
88
  boundingBox: Box3 | null;
84
89
  /** Bounding sphere enclosing every instance; nulled on mutation and recomputed on demand. */
@@ -69,6 +69,11 @@ export class InstancedMeshImpl extends Mesh {
69
69
  perObjectFrustumCulled = true;
70
70
  /** Whether instances are depth-sorted (via {@link customSort}) before drawing. */
71
71
  sortObjects = false;
72
+ /**
73
+ * Whether the mesh draws into the shadow map a given shadow camera renders. `null` draws into
74
+ * every map. A declined pass draws zero instances.
75
+ */
76
+ shadowFilter = null;
72
77
  /** Bounding box enclosing every instance; nulled on mutation and recomputed on demand. */
73
78
  boundingBox = null;
74
79
  /** Bounding sphere enclosing every instance; nulled on mutation and recomputed on demand. */
@@ -396,6 +401,13 @@ export class InstancedMeshImpl extends Mesh {
396
401
  this._unpatchMaterial = null;
397
402
  }
398
403
  onBeforeShadow(renderer, scene, camera, shadowCamera, geometry, depthMaterial, group) {
404
+ if (this.shadowFilter && !this.shadowFilter(shadowCamera)) {
405
+ // Declined: draw nothing, and skip the cull and sort nothing would read. The material is still
406
+ // patched, so three draws the zero instances with the program it already built for it.
407
+ this._unpatchMaterial = this.patchMaterial(depthMaterial);
408
+ this.count = 0;
409
+ return;
410
+ }
399
411
  this.onBeforeRender(renderer, scene, shadowCamera, geometry, depthMaterial, group);
400
412
  }
401
413
  onAfterShadow(renderer, scene, camera, shadowCamera, geometry, depthMaterial, group) {
@@ -1,6 +1,6 @@
1
1
  import { extend } from '@react-three/fiber';
2
2
  import { Matrix4, PlaneGeometry, Vector2, } from 'three';
3
- import { aimDepth } from '../../utils/math';
3
+ import { referenceDepth } from '../../utils/math';
4
4
  import { InstancedMeshImpl } from '../instanced/InstancedMesh';
5
5
  import { RaycastingSprites } from './RaycastingSprites';
6
6
  import { ANCHOR_SCHEMA, ANCHOR_UNIFORM, patchSpriteMaterial, spriteReferenceDepth, } from './sprite-material';
@@ -127,7 +127,7 @@ export class BatchedSpritesImpl extends InstancedMeshImpl {
127
127
  //
128
128
  // Reading `matrixWorld` rather than a scene object keeps this class free of `space/`, and it
129
129
  // answers under a host transform too, because whatever places the plan places this mesh with it.
130
- spriteReferenceDepth(material).value = aimDepth(camera, this.matrixWorld);
130
+ spriteReferenceDepth(material).value = referenceDepth(camera, this.matrixWorld);
131
131
  super.onBeforeRender(renderer, scene, camera, geometry, material, group);
132
132
  }
133
133
  patchMaterial(material) {
@@ -1,4 +1,6 @@
1
- import { type Object3D, Vector2 } from 'three';
1
+ import { type Intersection, type Object3D, type Raycaster, Vector2 } from 'three';
2
+ import { type DrawList } from '../instanced/FrustumCulling';
3
+ import { type Instances } from '../instanced/Instances';
2
4
  import { type RaycastHost, Raycasting } from '../instanced/Raycasting';
3
5
  /** What this sweep reads off the batch it tests, beyond what every instanced mesh offers. */
4
6
  interface RaycastHostSprites extends RaycastHost {
@@ -35,6 +37,12 @@ interface RaycastHostSprites extends RaycastHost {
35
37
  * the comments below for each piece.
36
38
  */
37
39
  export declare class RaycastingSprites extends Raycasting {
40
+ /**
41
+ * The depth the shader's correction is exact at, for the cast in progress: `0` for none. Read
42
+ * once per cast, as the draw reads it once per frame, from the camera the caster was aimed from.
43
+ */
44
+ private reference;
45
+ raycast(host: RaycastHostSprites, instances: Instances, drawList: DrawList | null, raycaster: Raycaster, intersects: Intersection[]): void;
38
46
  protected prepareInstance(host: RaycastHostSprites, objectIndex: number): Object3D;
39
47
  }
40
48
  export {};
@@ -1,5 +1,5 @@
1
- import { Matrix4, Sprite, SpriteMaterial, Vector2, Vector3 } from 'three';
2
- import { axisLength } from '../../utils/math';
1
+ import { Matrix4, Sprite, SpriteMaterial, Vector2, Vector3, } from 'three';
2
+ import { axisLength, referenceDepth } from '../../utils/math';
3
3
  import { Raycasting } from '../instanced/Raycasting';
4
4
  /**
5
5
  * Picking for a sprite batch: each member tested as the standing quad it actually draws.
@@ -26,13 +26,30 @@ import { Raycasting } from '../instanced/Raycasting';
26
26
  * the comments below for each piece.
27
27
  */
28
28
  export class RaycastingSprites extends Raycasting {
29
+ /**
30
+ * The depth the shader's correction is exact at, for the cast in progress: `0` for none. Read
31
+ * once per cast, as the draw reads it once per frame, from the camera the caster was aimed from.
32
+ */
33
+ reference = 0;
34
+ raycast(host, instances, drawList, raycaster, intersects) {
35
+ const { camera } = raycaster;
36
+ this.reference = camera ? referenceDepth(camera, host.matrixWorld) : 0;
37
+ if (this.reference > 0) {
38
+ _eye.setFromMatrixPosition(camera.matrixWorld);
39
+ _forward.setFromMatrixColumn(camera.matrixWorld, 2).normalize().negate();
40
+ }
41
+ super.raycast(host, instances, drawList, raycaster, intersects);
42
+ }
29
43
  prepareInstance(host, objectIndex) {
30
44
  const matrix = host.getMatrixAt(objectIndex, _matrix);
31
45
  // The shader takes the anchor from the instance matrix's translation and the scale from the
32
46
  // model matrix, and a world rotation must not spin a sprite. So the scratch carries a
33
47
  // translation and a scale and no rotation at all.
34
- const planToWorld = axisLength(host.matrixWorld, 0);
35
48
  _position.setFromMatrixPosition(matrix).applyMatrix4(host.matrixWorld);
49
+ // The shader's `spriteDepthScale`, so a sprite away from the aim depth is picked at the size
50
+ // it is drawn at rather than at its plan-unit size.
51
+ const depth = this.reference > 0 ? _offset.copy(_position).sub(_eye).dot(_forward) : 0;
52
+ const planToWorld = axisLength(host.matrixWorld, 0) * (depth > 0 ? depth / this.reference : 1);
36
53
  _sprite.matrixWorld
37
54
  .makeScale(planToWorld * axisLength(matrix, 0), planToWorld * axisLength(matrix, 1), 1)
38
55
  .setPosition(_position);
@@ -69,3 +86,6 @@ const _sprite = new Sprite(_material);
69
86
  const _matrix = new Matrix4();
70
87
  const _position = new Vector3();
71
88
  const _anchor = new Vector2();
89
+ const _eye = new Vector3();
90
+ const _forward = new Vector3();
91
+ const _offset = new Vector3();
@@ -177,15 +177,14 @@ const SPRITE_PROJECT = /* glsl */ `
177
177
  * the projection shrinks it, so the two cancel. At the reference depth the factor is one, which is
178
178
  * what keeps `bounds.size` meaning the same plan units it means today.
179
179
  *
180
- * Two cases opt out and return one. A `referenceDepth` of zero is the uninitialized value, which
181
- * leaves the old behavior in place rather than dividing by it. An orthographic projection performs
182
- * no divide to cancel, and `projectionMatrix[2][3]` is what tells the two apart, exactly as three's
183
- * own `isPerspectiveMatrix` does.
180
+ * A `referenceDepth` of zero opts out and returns one. The draw writes zero for a projection with
181
+ * no divide to cancel, and it is the uninitialized value too. Which projections divide is decided on
182
+ * the CPU by `referenceDepth` in `utils/math.ts`, not here: an exact `-1` in the projection's w row
183
+ * misses an external host's projection, which folds its unit conversion into that row.
184
184
  */
185
185
  const DEPTH_SCALE = /* glsl */ `
186
186
  float spriteDepthScale( const in float viewZ ) {
187
- bool isPerspective = projectionMatrix[ 2 ][ 3 ] == -1.0;
188
- if ( !isPerspective || ${REFERENCE_DEPTH_UNIFORM} <= 0.0 ) return 1.0;
187
+ if ( ${REFERENCE_DEPTH_UNIFORM} <= 0.0 ) return 1.0;
189
188
 
190
189
  return -viewZ / ${REFERENCE_DEPTH_UNIFORM};
191
190
  }
@@ -1,6 +1,6 @@
1
1
  import { Color, DataTexture, FloatType, Frustum, Matrix4, RGBAFormat, Sphere, Vector3, } from 'three';
2
2
  import { Y_DOWN_FLIP } from '../../space/Space';
3
- import { aimDepth } from '../../utils/math';
3
+ import { referenceDepth } from '../../utils/math';
4
4
  /**
5
5
  * The data texture a batch's shader reads each member's transform and style from: one 32-float row
6
6
  * per member, refilled once per draw with frustum culling folded in.
@@ -62,9 +62,7 @@ export class MemberTexture {
62
62
  // What a screen-space member's size is exact at, and where the camera looks from. Zero turns the
63
63
  // correction off, for an orthographic camera (no divide to cancel) and for one that never meets
64
64
  // the plan. See `depthScaleOf`.
65
- const reference = camera.isPerspectiveCamera
66
- ? aimDepth(camera, host.matrixWorld)
67
- : 0;
65
+ const reference = referenceDepth(camera, host.matrixWorld);
68
66
  _eye.setFromMatrixPosition(camera.matrixWorld);
69
67
  _forward.setFromMatrixColumn(camera.matrixWorld, 2).normalize().negate();
70
68
  for (let memberId = 0; memberId < rowCount; memberId++) {
@@ -56,6 +56,7 @@ export function LayoutDriver(props) {
56
56
  frameAt: -Infinity,
57
57
  changedAt: -Infinity,
58
58
  placedAt: -Infinity,
59
+ placedPixelSize: NaN,
59
60
  });
60
61
  useFrame((state) => {
61
62
  const { camera, gl, viewport } = state;
@@ -98,6 +99,11 @@ export function LayoutDriver(props) {
98
99
  *
99
100
  * Visibly means faster than {@link SETTLE_SPEED_PX_PER_S}. The controls' easing tail, which
100
101
  * creeps for hundreds of milliseconds after the plan looks still, therefore does not hold the pass.
102
+ *
103
+ * A zoom does not wait for the plan to settle: while the pixel size moves, a pass runs every
104
+ * {@link ZOOM_PLACEMENT_INTERVAL_MS}. A zoom is what changes how crowded the screen is, so a cluster
105
+ * a click flies into splits on the way in rather than once the flight has landed. A pan or a turn
106
+ * leaves the pixel size alone and still waits.
101
107
  * @param targets - The registry.
102
108
  * @param state - The debounce state, updated here.
103
109
  * @param context - The pass's context.
@@ -116,9 +122,14 @@ function runPlacement(targets, state, context, now) {
116
122
  state.frameAt = now;
117
123
  const pending = state.changedAt > state.placedAt;
118
124
  const owed = targets.needsPlacement || targets.placementDrifted;
119
- if (!owed && !(pending && now - state.changedAt >= PLACEMENT_DEBOUNCE_MS))
125
+ const settled = pending && now - state.changedAt >= PLACEMENT_DEBOUNCE_MS;
126
+ const zoomed = pending &&
127
+ context.pixelSize !== state.placedPixelSize &&
128
+ now - state.placedAt >= ZOOM_PLACEMENT_INTERVAL_MS;
129
+ if (!owed && !settled && !zoomed)
120
130
  return pending;
121
131
  state.placedAt = now;
132
+ state.placedPixelSize = context.pixelSize;
122
133
  targets.applyPlacement(context);
123
134
  return false;
124
135
  }
@@ -167,6 +178,11 @@ const LAYOUT_BUDGET_MS = 3;
167
178
  * enough that a drag or a run of wheel events reports once, not on every event.
168
179
  */
169
180
  const PLACEMENT_DEBOUNCE_MS = 60;
181
+ /**
182
+ * How often the placement pass runs while the pixel size moves, in milliseconds: the "few times a
183
+ * second" a pass can afford, and often enough that a cluster splits within a fraction of a zoom.
184
+ */
185
+ const ZOOM_PLACEMENT_INTERVAL_MS = 150;
170
186
  /**
171
187
  * How fast the plan may move on screen, in CSS pixels a second, and still count as still: one CSS
172
188
  * pixel a frame at 60 Hz. Each frame is held against its own time step, so the rule is the same at
@@ -1,9 +1,9 @@
1
1
  import { createContext, use, useEffect } from 'react';
2
- import { isImageDef, isLayerDef, isPlacementTarget } from '../types/guards';
2
+ import { isLayerDef, isPlacementTarget } from '../types/guards';
3
3
  import { subscribeDef, writeChanged } from '../update';
4
4
  import { createLogger } from '../utils/logging';
5
5
  import { culledBy } from './def-culling';
6
- import { createPlacement } from './placement';
6
+ import { createPlacement, placementBoundsOf, placementOriginOf, } from './placement';
7
7
  const logger = createLogger('layout');
8
8
  /**
9
9
  * The renderer's re-layout registry. Absent outside a renderer, where a layer simply registers
@@ -83,6 +83,11 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
83
83
  * resize. Seeded at registration, which is when the def's instance wrote what it held.
84
84
  */
85
85
  const drawnHidden = new WeakMap();
86
+ /**
87
+ * What the pass measured of each registered participant when it last read it: the baseline an
88
+ * `update()` is compared with to tell a drift.
89
+ */
90
+ const readings = new WeakMap();
86
91
  /**
87
92
  * The write queue, in priority order: defs a rule flipped between hidden and shown, then every
88
93
  * other def a rule changed, then the ones a drain found outside the frustum. Sets, not arrays,
@@ -119,16 +124,33 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
119
124
  if (def.onScale && layouts.get(def) !== current) {
120
125
  const changed = def.onScale(view);
121
126
  layouts.set(def, current);
127
+ rebaseline(def, changed);
122
128
  if (changed?.length)
123
129
  report(changed);
124
130
  }
125
131
  if (def.onRoll && rolls.get(def) !== currentRoll) {
126
132
  const changed = def.onRoll(view);
127
133
  rolls.set(def, currentRoll);
134
+ rebaseline(def, changed);
128
135
  if (changed?.length)
129
136
  report(changed);
130
137
  }
131
138
  }
139
+ /**
140
+ * Takes what a layout rule wrote into the participants' baselines. A rule follows the camera, and
141
+ * the driver paces the passes a camera move owes, a zoom included. Without this, the next
142
+ * `update()` of a pin, such as a fade's next frame, would read a zoom's resize as a drift and run
143
+ * the pass at frame rate for as long as the zoom lasts.
144
+ * @param def - The def whose rule ran.
145
+ * @param changed - What the rule reported changed.
146
+ */
147
+ function rebaseline(def, changed) {
148
+ for (const each of [def, ...(changed ?? [])]) {
149
+ const seen = readings.get(each);
150
+ if (seen)
151
+ remeasure(each, seen);
152
+ }
153
+ }
132
154
  /**
133
155
  * Writes a def now — the layer path or the slot path, per `writeChanged` — and records whether
134
156
  * what it drew was hidden.
@@ -242,6 +264,7 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
242
264
  // again.
243
265
  const unsubscribes = defs.filter(isPlacementTarget).map((def) => {
244
266
  const seen = measuredBy(def);
267
+ readings.set(def, seen);
245
268
  return subscribeDef(def, () => {
246
269
  if (!remeasure(def, seen))
247
270
  return;
@@ -266,6 +289,7 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
266
289
  queued.delete(def);
267
290
  deferred.delete(def);
268
291
  placement.forget(def);
292
+ readings.delete(def);
269
293
  }
270
294
  };
271
295
  },
@@ -355,7 +379,8 @@ function declaresPlacement(def) {
355
379
  return def.placement !== undefined;
356
380
  }
357
381
  /**
358
- * Reads what the pass measures of a participant: the box its bounds, origin and padding describe.
382
+ * Reads what the pass measures of a participant: the box its placement rect, origin and padding
383
+ * describe, which are its own bounds and origin unless it gives `placement.bounds`.
359
384
  * @param def - The participant.
360
385
  * @returns The reading.
361
386
  */
@@ -372,8 +397,8 @@ function measuredBy(def) {
372
397
  * @returns Whether the reading changed.
373
398
  */
374
399
  function remeasure(def, into) {
375
- const { bounds } = def;
376
- const origin = isImageDef(def) ? def.origin : undefined;
400
+ const bounds = placementBoundsOf(def);
401
+ const origin = placementOriginOf(def);
377
402
  const padding = def.placement?.padding;
378
403
  const next = _measure;
379
404
  next[0] = bounds.center.x;
@@ -1,3 +1,4 @@
1
+ import { Rect } from '@expofp/geometry';
1
2
  import { type Camera } from 'three';
2
3
  import { type Space } from '../../space/Space';
3
4
  import { type ImageDef, type TextDef } from '../../types/defs';
@@ -25,6 +26,19 @@ import { type PlacementBox } from './grid';
25
26
  * @returns The box, or nothing when the def has no extent or its anchor does not project.
26
27
  */
27
28
  export declare function screenBoxOf(def: ImageDef | TextDef, space: Space, camera: Camera, pixelSize: number, out: PlacementBox): PlacementBox | undefined;
29
+ /**
30
+ * The rect the placement pass measures a def by: its `placement.bounds`, or its own bounds.
31
+ * @param def - The participant.
32
+ * @returns The rect.
33
+ */
34
+ export declare function placementBoundsOf(def: ImageDef | TextDef): Rect;
35
+ /**
36
+ * The point of {@link placementBoundsOf}'s rect that its center names: `placement.origin`, or the
37
+ * def's own origin.
38
+ * @param def - The participant.
39
+ * @returns The origin, or nothing for a centered one.
40
+ */
41
+ export declare function placementOriginOf(def: ImageDef | TextDef): [number, number] | undefined;
28
42
  /**
29
43
  * The screen rectangle a constant-pixel-size sprite occupies when its anchor stands at a plan
30
44
  * point, in CSS pixels from the canvas's top-left corner.
@@ -26,10 +26,27 @@ export function screenBoxOf(def, space, camera, pixelSize, out) {
26
26
  const scale = pixelSize;
27
27
  if (!Number.isFinite(scale) || scale <= 0)
28
28
  return undefined;
29
- const bounds = def.bounds;
30
- const origin = isImageDef(def) ? def.origin : undefined;
29
+ const bounds = placementBoundsOf(def);
30
+ const origin = placementOriginOf(def);
31
31
  return spriteBoxAt(bounds.center.x, bounds.center.y, bounds.elevation, bounds.size.x / scale, bounds.size.y / scale, origin, bounds.rotation, space, camera, out);
32
32
  }
33
+ /**
34
+ * The rect the placement pass measures a def by: its `placement.bounds`, or its own bounds.
35
+ * @param def - The participant.
36
+ * @returns The rect.
37
+ */
38
+ export function placementBoundsOf(def) {
39
+ return def.placement?.bounds ?? def.bounds;
40
+ }
41
+ /**
42
+ * The point of {@link placementBoundsOf}'s rect that its center names: `placement.origin`, or the
43
+ * def's own origin.
44
+ * @param def - The participant.
45
+ * @returns The origin, or nothing for a centered one.
46
+ */
47
+ export function placementOriginOf(def) {
48
+ return def.placement?.origin ?? (isImageDef(def) ? def.origin : undefined);
49
+ }
33
50
  /**
34
51
  * The screen rectangle a constant-pixel-size sprite occupies when its anchor stands at a plan
35
52
  * point, in CSS pixels from the canvas's top-left corner.
@@ -1,2 +1,3 @@
1
+ export { placementBoundsOf, placementOriginOf } from './box';
1
2
  export { createPlacement, type Placement, type PlacementContext } from './pass';
2
3
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1,2 @@
1
+ export { placementBoundsOf, placementOriginOf } from './box';
1
2
  export { createPlacement } from './pass';
@@ -1,6 +1,6 @@
1
- import { isImageDef, isPlacementTarget } from '../../types/guards';
1
+ import { isPlacementTarget } from '../../types/guards';
2
2
  import { createLogger } from '../../utils/logging';
3
- import { paddedBox, screenBoxOf, spriteBoxAt } from './box';
3
+ import { paddedBox, placementBoundsOf, placementOriginOf, screenBoxOf, spriteBoxAt } from './box';
4
4
  import { overlaps, PlacementGrid } from './grid';
5
5
  /**
6
6
  * Builds a renderer's placement pass.
@@ -470,10 +470,10 @@ function markerOf(scope) {
470
470
  * @returns The box, or nothing when the anchor does not project or nothing has an extent.
471
471
  */
472
472
  function markerBoxOf(members, marker, context, out) {
473
- const { x, y, elevation } = centroidOf(members, _centroid);
473
+ const { x, y, elevation, unitCount } = centroidOf(members, _centroid);
474
474
  const { space, camera, pixelSize } = context;
475
475
  if (marker !== undefined) {
476
- const { width, height, origin } = marker;
476
+ const { width, height, origin } = typeof marker === 'function' ? marker(members, unitCount) : marker;
477
477
  return spriteBoxAt(x, y, elevation, width, height, origin, 0, space, camera, out);
478
478
  }
479
479
  if (!Number.isFinite(pixelSize) || pixelSize <= 0)
@@ -481,12 +481,12 @@ function markerBoxOf(members, marker, context, out) {
481
481
  for (const def of members) {
482
482
  if ((def.placement?.overlap ?? 'never') === 'always')
483
483
  continue;
484
- const { size, rotation } = def.bounds;
484
+ const { size, rotation } = placementBoundsOf(def);
485
485
  const width = size.x / pixelSize;
486
486
  const height = size.y / pixelSize;
487
487
  if (!(width > 0) || !(height > 0))
488
488
  continue;
489
- const origin = isImageDef(def) ? def.origin : undefined;
489
+ const origin = placementOriginOf(def);
490
490
  return spriteBoxAt(x, y, elevation, width, height, origin, rotation, space, camera, out);
491
491
  }
492
492
  return undefined;
@@ -504,7 +504,8 @@ function markerBoxOf(members, marker, context, out) {
504
504
  * @returns The cluster.
505
505
  */
506
506
  function clusterOf(members) {
507
- return centroidOf(members, { unitCount: 0, x: 0, y: 0, elevation: 0 });
507
+ const { unitCount, x, y, elevation } = centroidOf(members, _centroid);
508
+ return { unitCount, x, y, elevation, members: [...members] };
508
509
  }
509
510
  /**
510
511
  * Folds one cluster's members into its unit count, anchor and elevation, as {@link clusterOf}
@@ -524,7 +525,7 @@ function centroidOf(members, out) {
524
525
  let sumY = 0;
525
526
  let count = 0;
526
527
  do {
527
- const { bounds } = members[i];
528
+ const bounds = placementBoundsOf(members[i]);
528
529
  sumX += bounds.center.x;
529
530
  sumY += bounds.center.y;
530
531
  elevation = Math.max(elevation, bounds.elevation);
@@ -74,12 +74,13 @@ export declare function usePointerProps(layer: LayerDef, visible: boolean): Poin
74
74
  /**
75
75
  * Makes the canvas pick the way the renderer draws, for as long as the component is mounted.
76
76
  *
77
- * R3F's `events.filter` is the one hook into picking that sees the whole hit list, which is why both
78
- * corrections live there: {@link occludeHits} drops what hidden geometry stands in front of, and
79
- * {@link orderCoplanarHits} settles what the depth buffer never ordered. Both are the renderer's own
77
+ * R3F's `events.filter` is the one hook into picking that sees the whole hit list, which is why the
78
+ * corrections live there: {@link occludeHits} drops what hidden geometry stands in front of,
79
+ * {@link orderCoplanarHits} settles what the depth buffer never ordered, and
80
+ * {@link liftOverlayHits} puts what draws over the scene ahead of what it draws over. Both are the renderer's own
80
81
  * reading of its scene, so the whole arrangement is here rather than at whichever component mounts
81
82
  * it — a caller wires picking by calling this, and nothing outside this module has to know that there
82
- * are two halves or which order they run in.
83
+ * are three steps or which order they run in.
83
84
  */
84
85
  export declare function usePickFilter(): void;
85
86
  /**
@@ -135,8 +136,9 @@ export declare function resolveHit(hit: Intersection): RenderableDef | undefined
135
136
  export declare function missedPoint(raycaster: Raycaster, scene: Object3D, space: Space): PlanPoint;
136
137
  /**
137
138
  * Drops the hits that geometry with no handlers hides, so a booth behind a wall or a model, opaque
138
- * or translucent, is not picked. The first half of R3F's `events.filter`, which runs on its
139
- * nearest-first hits; {@link orderCoplanarHits} is the second, over what survives.
139
+ * or translucent, is not picked. The first step of R3F's `events.filter`, which runs on its
140
+ * nearest-first hits; {@link orderCoplanarHits} and {@link liftOverlayHits} follow, over what
141
+ * survives.
140
142
  *
141
143
  * R3F raycasts only interactive layers, so it cannot see what stands in front of them. This casts
142
144
  * the same ray at the whole scene and cuts the hits at the nearest object no interactive layer
@@ -145,12 +147,31 @@ export declare function missedPoint(raycaster: Raycaster, scene: Object3D, space
145
147
  * occluder, the least separation at which the depth buffer draws two surfaces in order. Nearer
146
148
  * than that, the occluder is drawn on the hit, not in front of it. A click with every hit dropped is
147
149
  * a miss, as a click on the occluder was before.
150
+ *
151
+ * What draws over the scene with depth testing off is neither cut nor an occluder: nothing in the
152
+ * scene hides it on screen, and it hides only by covering, which {@link liftOverlayHits} orders.
148
153
  * @param hits - R3F's hits, nearest first.
149
154
  * @param state - The root's state, holding the ray already aimed at the pointer.
150
155
  * @param space - The scene's space, whose scale turns the plan-unit separation into a world one.
151
156
  * @returns The hits in front of the nearest occluder.
152
157
  */
153
158
  export declare function occludeHits(hits: Intersection[], state: RootState, space: Space): Intersection[];
159
+ /**
160
+ * Puts the hits on what draws over the scene first, the one drawn last leading, ahead of every hit
161
+ * the depth buffer ordered. The last step of R3F's `events.filter`.
162
+ *
163
+ * An overlay layer draws with depth testing off (see {@link LayerDef.overlay}), so what it draws
164
+ * covers the scene wherever it stands along the ray. A screen-space sprite stands upright through
165
+ * its anchor, so a booth or a model can stand nearer to the camera than its quad does while the
166
+ * sprite is drawn over them both. Picked by distance, that booth would take a click meant for a pin
167
+ * drawn on top of it. {@link occludeHits} keeps such a hit for the same reason.
168
+ *
169
+ * Among themselves such hits have no depth either: painter's order alone decides which one shows, so
170
+ * they are ordered by where they draw, last first, along the keys {@link orderCoplanarHits} reads.
171
+ * @param hits - The hits, in pick order so far.
172
+ * @returns The hits in pick order.
173
+ */
174
+ export declare function liftOverlayHits(hits: Intersection[]): Intersection[];
154
175
  /**
155
176
  * Reorders the hits the depth buffer never separated, so the one drawn last is picked first. R3F's
156
177
  * `events.filter`, after {@link occludeHits} has cut away what is hidden.