@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
@@ -55,12 +55,13 @@ export function usePointerProps(layer, visible) {
55
55
  /**
56
56
  * Makes the canvas pick the way the renderer draws, for as long as the component is mounted.
57
57
  *
58
- * R3F's `events.filter` is the one hook into picking that sees the whole hit list, which is why both
59
- * corrections live there: {@link occludeHits} drops what hidden geometry stands in front of, and
60
- * {@link orderCoplanarHits} settles what the depth buffer never ordered. Both are the renderer's own
58
+ * R3F's `events.filter` is the one hook into picking that sees the whole hit list, which is why the
59
+ * corrections live there: {@link occludeHits} drops what hidden geometry stands in front of,
60
+ * {@link orderCoplanarHits} settles what the depth buffer never ordered, and
61
+ * {@link liftOverlayHits} puts what draws over the scene ahead of what it draws over. Both are the renderer's own
61
62
  * reading of its scene, so the whole arrangement is here rather than at whichever component mounts
62
63
  * it — a caller wires picking by calling this, and nothing outside this module has to know that there
63
- * are two halves or which order they run in.
64
+ * are three steps or which order they run in.
64
65
  */
65
66
  export function usePickFilter() {
66
67
  const setEvents = useThree((state) => state.setEvents);
@@ -72,7 +73,7 @@ export function usePickFilter() {
72
73
  // Cut first, then order: dropping what is hidden cannot move the survivors along the ray,
73
74
  // and ordering hits that were about to be dropped is work for nothing.
74
75
  const visible = occludeHits(hits, state, space);
75
- return orderCoplanarHits(visible, space);
76
+ return liftOverlayHits(orderCoplanarHits(visible, space));
76
77
  },
77
78
  });
78
79
  }, [setEvents, space]);
@@ -163,8 +164,9 @@ export function missedPoint(raycaster, scene, space) {
163
164
  }
164
165
  /**
165
166
  * Drops the hits that geometry with no handlers hides, so a booth behind a wall or a model, opaque
166
- * or translucent, is not picked. The first half of R3F's `events.filter`, which runs on its
167
- * nearest-first hits; {@link orderCoplanarHits} is the second, over what survives.
167
+ * or translucent, is not picked. The first step of R3F's `events.filter`, which runs on its
168
+ * nearest-first hits; {@link orderCoplanarHits} and {@link liftOverlayHits} follow, over what
169
+ * survives.
168
170
  *
169
171
  * R3F raycasts only interactive layers, so it cannot see what stands in front of them. This casts
170
172
  * the same ray at the whole scene and cuts the hits at the nearest object no interactive layer
@@ -173,6 +175,9 @@ export function missedPoint(raycaster, scene, space) {
173
175
  * occluder, the least separation at which the depth buffer draws two surfaces in order. Nearer
174
176
  * than that, the occluder is drawn on the hit, not in front of it. A click with every hit dropped is
175
177
  * a miss, as a click on the occluder was before.
178
+ *
179
+ * What draws over the scene with depth testing off is neither cut nor an occluder: nothing in the
180
+ * scene hides it on screen, and it hides only by covering, which {@link liftOverlayHits} orders.
176
181
  * @param hits - R3F's hits, nearest first.
177
182
  * @param state - The root's state, holding the ray already aimed at the pointer.
178
183
  * @param space - The scene's space, whose scale turns the plan-unit separation into a world one.
@@ -184,12 +189,35 @@ export function occludeHits(hits, state, space) {
184
189
  const { interaction } = state.internal;
185
190
  const occluder = state.raycaster
186
191
  .intersectObject(state.scene, true)
187
- .find((hit) => !isInteractive(hit.object, interaction));
192
+ .find((hit) => !isInteractive(hit.object, interaction) && !drawsOverScene(hit.object));
188
193
  if (!occluder)
189
194
  return hits;
190
195
  // Along the ray, a pitched view only lengthens the gap between two surfaces, never shortens it.
191
196
  const cut = occluder.distance + depthSeparation(space.scale);
192
- return hits.filter((hit) => hit.distance <= cut);
197
+ return hits.filter((hit) => hit.distance <= cut || drawsOverScene(hit.object));
198
+ }
199
+ /**
200
+ * Puts the hits on what draws over the scene first, the one drawn last leading, ahead of every hit
201
+ * the depth buffer ordered. The last step of R3F's `events.filter`.
202
+ *
203
+ * An overlay layer draws with depth testing off (see {@link LayerDef.overlay}), so what it draws
204
+ * covers the scene wherever it stands along the ray. A screen-space sprite stands upright through
205
+ * its anchor, so a booth or a model can stand nearer to the camera than its quad does while the
206
+ * sprite is drawn over them both. Picked by distance, that booth would take a click meant for a pin
207
+ * drawn on top of it. {@link occludeHits} keeps such a hit for the same reason.
208
+ *
209
+ * Among themselves such hits have no depth either: painter's order alone decides which one shows, so
210
+ * they are ordered by where they draw, last first, along the keys {@link orderCoplanarHits} reads.
211
+ * @param hits - The hits, in pick order so far.
212
+ * @returns The hits in pick order.
213
+ */
214
+ export function liftOverlayHits(hits) {
215
+ const over = hits.filter((hit) => drawsOverScene(hit.object));
216
+ if (over.length === 0)
217
+ return hits;
218
+ // `sort` is stable, so hits nothing orders keep the order they came in.
219
+ over.sort((a, b) => compareDrawOrder(b, a));
220
+ return [...over, ...hits.filter((hit) => !drawsOverScene(hit.object))];
193
221
  }
194
222
  /**
195
223
  * Reorders the hits the depth buffer never separated, so the one drawn last is picked first. R3F's
@@ -326,6 +354,19 @@ function groupOrderOf(object) {
326
354
  }
327
355
  return 0;
328
356
  }
357
+ /**
358
+ * Whether an object draws over the scene: it has a material, and none of its materials depth tests.
359
+ * That is what an overlay layer gives its flat content.
360
+ * @param object - The object hit.
361
+ * @returns Whether nothing in the scene can hide it.
362
+ */
363
+ function drawsOverScene(object) {
364
+ const material = object.material;
365
+ if (!material)
366
+ return false;
367
+ const materials = Array.isArray(material) ? material : [material];
368
+ return materials.length > 0 && materials.every((each) => !each.depthTest);
369
+ }
329
370
  /**
330
371
  * Whether an object sits in an interactive layer: it, or an ancestor, carries R3F handlers.
331
372
  * @param object - The object hit.
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  export { type CameraAPI, type CameraAxes, type CameraState, type ControlsConfig, type InertiaConfig, type PanConfig, type RollConfig, type TransitionOptions, useCameraAPI, useCameraGesture, useCameraMoveEnd, useCameraState, type ZoomConfig, type ZoomToOptions, } from './controls';
2
2
  export { prepareDebug } from './debug/debug-chunk';
3
- export { useDebugPanel } from './debug/debug-context';
3
+ export { useDebugPanel, useGui } from './debug/debug-context';
4
4
  export { type AmbientOcclusionProps, type ContactShadowProps, type EnvironmentProps, type LightingProps, type SunShadowProps, } from './objects/lighting';
5
5
  export * from './Renderer';
6
6
  export { type CameraProps, type SmoothTime } from './space/Camera';
package/dist/index.js CHANGED
@@ -4,8 +4,8 @@
4
4
  export { useCameraAPI, useCameraGesture, useCameraMoveEnd, useCameraState, } from './controls';
5
5
  // The debug chunk's preload, for an external host that must create its context instrumented.
6
6
  export { prepareDebug } from './debug/debug-chunk';
7
- // Publishing a host's own values into the debug panel.
8
- export { useDebugPanel } from './debug/debug-context';
7
+ // Adding a host's own folders and values to the debug panel.
8
+ export { useDebugPanel, useGui } from './debug/debug-context';
9
9
  export * from './Renderer';
10
10
  export { useViewport } from './space/viewport';
11
11
  export * from './types/defs';
@@ -211,7 +211,7 @@ function AtlasMesh(props) {
211
211
  // args is a frozen snapshot, so R3F never rebuilds the mesh. The ref arrow, rather than
212
212
  // ref={container.bind}, keeps the React Compiler from inferring container itself as a ref and
213
213
  // rejecting its render reads.
214
- const mesh = kind === 'sprite' ? (_jsx(BatchedSprites, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM, opacityUniform: OPACITY_UNIFORM }) })) : (_jsxs(InstancedMesh, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: [_jsx("planeGeometry", {}), _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM, opacityUniform: OPACITY_UNIFORM })] }));
214
+ const mesh = kind === 'sprite' ? (_jsx(BatchedSprites, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM, opacityUniform: OPACITY_UNIFORM, lodBias: -1 }) })) : (_jsxs(InstancedMesh, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: [_jsx("planeGeometry", {}), _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM, opacityUniform: OPACITY_UNIFORM })] }));
215
215
  return (_jsxs(_Fragment, { children: [mesh, placements.slice(0, mounted).map((packed) => (_jsx(ImageInstance, { def: packed.def, packed: packed, container: container }, `${defKey(packed.def)}:${packed.uv.u0}:${packed.uv.v0}`)))] }));
216
216
  }
217
217
  /**
@@ -1,32 +1,39 @@
1
1
  /**
2
- * Props for {@link Lighting}: every value the debug GUI can move, apart from the two that aim the
3
- * key light, grouped the way the GUI's Lighting folder groups them.
2
+ * Props for {@link Lighting}: every value the debug GUI can move, apart from the three that make the
3
+ * key light follow the camera, grouped the way the GUI's Lighting folder groups them.
4
4
  *
5
5
  * Each one is optional, and each one overrides the design's own default for as long as it is given.
6
- * The pitch and `trackPitch` are deliberately absent. Where the key light points is the design's
7
- * decision rather than a caller's, and the GUI keeps both of them for settling it.
6
+ * `followCamera`, the pitch and `trackPitch` are deliberately absent. Whether the key light follows
7
+ * the camera is the design's decision rather than a caller's, and the GUI keeps them for settling
8
+ * it.
8
9
  *
9
10
  * **A prop beats the GUI only when the prop changes.** {@link Lighting} writes these into the rig
10
11
  * and into the scene's effect state from an effect keyed on the values themselves, so a control the
11
12
  * GUI moved stays moved until a caller passes something different.
12
13
  */
13
- export interface LightingProps extends Partial<Pick<LightSettings, 'contrast' | 'skyColor' | 'groundColor' | 'directionalColor'>> {
14
- /** The studio HDRI: how much of a roof's light it gives, and its turn. */
14
+ export interface LightingProps extends Partial<Pick<LightSettings, 'sun'>> {
15
+ /** The studio environment's turn. */
15
16
  environment?: EnvironmentProps;
16
- /** The shade every darkening term blends toward, as a CSS hex string. */
17
+ /**
18
+ * The shade the contact shadow and ambient occlusion blend toward, as a CSS hex string. The sun's
19
+ * shadow takes a share of the light instead, untinted.
20
+ */
17
21
  shadowColor?: string;
18
22
  /** The opacity of every model whose def sets none, from `0` to `1`. */
19
23
  modelOpacity?: number;
20
- /** The fixed sun's shadow. */
24
+ /** The fixed sun: where it stands, and its shadow. */
21
25
  sunShadow?: SunShadowProps;
22
26
  /** The darkening toward a volume's base. */
23
27
  contactShadow?: ContactShadowProps;
24
28
  /** Screen-space ambient occlusion. */
25
29
  ambientOcclusion?: AmbientOcclusionProps;
26
30
  }
27
- /** The studio HDRI's values a caller can set; each one omitted keeps the default. */
31
+ /** The studio environment's values a caller can set; each one omitted keeps the default. */
28
32
  export type EnvironmentProps = Partial<EnvironmentSettings>;
29
- /** The sun shadow's values a caller can set, as the GUI's Sun shadows folder lists them. */
33
+ /**
34
+ * The sun shadow's values a caller can set. Heading and elevation are the caller's alone: the GUI
35
+ * has no control for them.
36
+ */
30
37
  export type SunShadowProps = Partial<SunShadowSettings>;
31
38
  /** The contact shadow's values, as the GUI's Contact shadow folder lists them. */
32
39
  export interface ContactShadowProps {
@@ -51,22 +58,26 @@ export interface AmbientOcclusionProps {
51
58
  /** How far it blends an occluded fragment toward the shade, from `0` to `1`. */
52
59
  strength?: number;
53
60
  }
54
- /** The studio HDRI's part of the rig: every value set. */
61
+ /** The studio environment's part of the rig: every value set. */
55
62
  export interface EnvironmentSettings {
56
- /** The share of a roof's light the HDRI gives, from `0` (off) to `1` (all of it). */
57
- share: number;
58
- /** The HDRI's turn about the plan's up axis. */
63
+ /** The studio's turn about the plan's up axis. */
59
64
  rotationDegrees: number;
60
65
  }
61
- /** The sun shadow's part of the rig: every value set. */
66
+ /**
67
+ * The sun's part of the rig: every value set. Its heading and elevation aim the directional light as
68
+ * well as the shadow, unless {@link LightSettings.followCamera} is on.
69
+ */
62
70
  export interface SunShadowSettings {
63
- /** Whether the shadow-only sun casts shadow-mapped shadows. */
71
+ /** Whether the sun casts shadow-mapped shadows. */
64
72
  enabled: boolean;
65
73
  /** The sun's heading, counterclockwise on screen from the plan's `+x`. */
66
74
  headingDegrees: number;
67
75
  /** The sun's height above the horizon. */
68
76
  elevationDegrees: number;
69
- /** How far a roof or the floor in full shadow blends toward the shadow color, `0` to `1`. */
77
+ /**
78
+ * The share of the sun's direct light a surface in full shadow loses, `0` to `1`: three's
79
+ * `shadow.intensity`. The unlit plan floor and a host's map darken by the same fraction.
80
+ */
70
81
  strength: number;
71
82
  }
72
83
  /**
@@ -76,36 +87,43 @@ export interface SunShadowSettings {
76
87
  * few numbers and no render. A remount gives a fresh rig rather than reusing module state.
77
88
  */
78
89
  export interface LightSettings {
79
- /** Whether the light copies the camera's backward axis in full, the pre-overhaul behavior. */
90
+ /**
91
+ * Whether the directional light turns with the camera's heading, the behavior before the fixed
92
+ * sun. Off, the sun's heading and elevation aim it.
93
+ */
94
+ followCamera: boolean;
95
+ /**
96
+ * Whether the light copies the camera's backward axis in full, the pre-overhaul behavior. Read
97
+ * only while `followCamera` is on.
98
+ */
80
99
  trackPitch: boolean;
81
- /** The light's angle from the plan's up axis, in degrees. Unread while `trackPitch` is on. */
100
+ /**
101
+ * The light's angle from the plan's up axis, in degrees. Read only while `followCamera` is on and
102
+ * `trackPitch` is off.
103
+ */
82
104
  pitchDegrees: number;
83
105
  /**
84
- * How directional the rig is, from `0` (pure hemisphere, flat) to `1` (the most directional light
85
- * this pitch and these colors take before a wall clips). Normalized rather than an intensity ratio,
86
- * whose usable range moves with the pitch. See {@link intensitiesFromContrast}.
106
+ * The sun's light on a surface that faces it, as a share of the surface's color, from `0` to `1`.
107
+ * The studio fills a roof up to its color, so this sets how much brighter a sunward wall is than a
108
+ * shaded one.
87
109
  */
88
- contrast: number;
89
- /** Hemisphere sky color, as a CSS hex string. */
90
- skyColor: string;
91
- /** Hemisphere ground color, which every downward face receives. */
92
- groundColor: string;
93
- /** Directional color, warm against the cool sky so lit faces separate by temperature too. */
94
- directionalColor: string;
95
- /** The studio HDRI. */
110
+ sun: number;
111
+ /** The studio environment. */
96
112
  environment: EnvironmentSettings;
97
- /** The fixed sun's shadow. */
113
+ /** The fixed sun: where it stands, and its shadow. */
98
114
  sunShadow: SunShadowSettings;
99
115
  }
100
116
  /**
101
- * Scene lighting: a hemisphere fill along the plan's up axis, and a warm directional light at a
102
- * fixed pitch on the camera's heading. The one intensity control is `contrast`, and `Lighting`
103
- * derives both `π`-unit intensities from it every frame — so an up-facing surface (a roof) lands on
104
- * its authored color and no surface the design accounts for clips.
117
+ * Scene lighting: a directional light from the fixed sun, which casts the shadow too, and the studio
118
+ * environment. A GUI toggle puts the light back on the camera's heading at a fixed pitch.
119
+ *
120
+ * **One rule keeps a roof at its color: the sun and the studio sum to `1` on an up-facing surface.**
121
+ * The sun gives a roof `sun · cos θ`, and the studio fills the rest. Walls are darker than roofs
122
+ * because the solid shapes' side shade darkens their albedo, not because the rig is balanced
123
+ * against them, so nothing here searches for a clip.
105
124
  *
106
125
  * That is also why the renderer skips tone mapping (see `Renderer.tsx` and `ExternalCanvas.tsx`): a
107
- * curve brings an unbounded light sum back into range, and `contrast` keeps this rig's sum in range
108
- * to begin with, at every pitch.
126
+ * curve brings an unbounded light sum back into range, and this rig's sum is in range to begin with.
109
127
  *
110
128
  * Only lit materials see the lights — solid shape batches and models. Every 2D primitive draws
111
129
  * through a `MeshBasicMaterial`, so lines, text and images are unaffected.
@@ -116,7 +134,7 @@ export interface LightSettings {
116
134
  * under any fit. The directional light needs its target under the same matrix for that, since its
117
135
  * direction is the difference of two world positions.
118
136
  * @param props - The values a caller set, any subset; see {@link LightingProps}.
119
- * @returns The two lights, and the directional light's target.
137
+ * @returns The two lights, the directional light's target, and the shadow catcher.
120
138
  */
121
139
  export declare function Lighting(props: LightingProps): import("react").JSX.Element;
122
140
  //# sourceMappingURL=Lighting.d.ts.map