@expofp/renderer 3.45.16 → 3.46.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
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
3
  export { useDebugPanel } from './debug/debug-context';
4
- export { type LightingProps, type ShadowProps } from './objects/lighting';
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';
7
7
  export { type CanvasPoint, type CanvasPointLike, type PlanPoint, type PlanPointLike, } from './space/Space';
@@ -1,5 +1,6 @@
1
1
  /**
2
- * Props for {@link Lighting}: every value the debug GUI can move, apart from the two that aim the key light.
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.
3
4
  *
4
5
  * Each one is optional, and each one overrides the design's own default for as long as it is given.
5
6
  * The pitch and `trackPitch` are deliberately absent. Where the key light points is the design's
@@ -9,39 +10,64 @@
9
10
  * and into the scene's effect state from an effect keyed on the values themselves, so a control the
10
11
  * GUI moved stays moved until a caller passes something different.
11
12
  */
12
- export interface LightingProps extends Partial<Omit<LightSettings, 'trackPitch' | 'pitchDegrees'>> {
13
- /** The shade both darkening terms blend toward, and each term's own numbers. */
14
- shadow?: ShadowProps;
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. */
15
+ environment?: EnvironmentProps;
16
+ /** The shade every darkening term blends toward, as a CSS hex string. */
17
+ shadowColor?: string;
18
+ /** The opacity of every model whose def sets none, from `0` to `1`. */
19
+ modelOpacity?: number;
20
+ /** The fixed sun's shadow. */
21
+ sunShadow?: SunShadowProps;
22
+ /** The darkening toward a volume's base. */
23
+ contactShadow?: ContactShadowProps;
24
+ /** Screen-space ambient occlusion. */
25
+ ambientOcclusion?: AmbientOcclusionProps;
15
26
  }
16
- /**
17
- * The darkening values: the shade both terms share, the contact shadow's two numbers, and ambient
18
- * occlusion's switch and two numbers.
19
- *
20
- * One object rather than six loose props, because they are one visual decision. The names are the
21
- * GUI's own labels, so a caller and a slider talk about the same thing — and so that the two
22
- * strengths cannot be mistaken for each other, which is the reason the GUI renamed them.
23
- *
24
- * Omit a value to keep the design's own default. `CONTACT_SHADOW_DEFAULTS` and `OCCLUSION_DEFAULTS`
25
- * are where those live, each beside the term that owns it.
26
- */
27
- export interface ShadowProps {
28
- /** The shade both terms blend toward, as a CSS hex string. */
29
- color?: string;
30
- /** The contact shadow's reach above a volume's base, in plan units. */
31
- contactDistance?: number;
32
- /** How far the contact shadow blends a volume's base toward the shade, from `0` to `1`. */
33
- contactStrength?: number;
27
+ /** The studio HDRI's values a caller can set; each one omitted keeps the default. */
28
+ export type EnvironmentProps = Partial<EnvironmentSettings>;
29
+ /** The sun shadow's values a caller can set, as the GUI's Sun shadows folder lists them. */
30
+ export type SunShadowProps = Partial<SunShadowSettings>;
31
+ /** The contact shadow's values, as the GUI's Contact shadow folder lists them. */
32
+ export interface ContactShadowProps {
33
+ /** Whether the contact shadow draws. */
34
+ enabled?: boolean;
35
+ /** Its reach above a volume's base, in plan units. */
36
+ distance?: number;
37
+ /** How far it blends a volume's base toward the shade, from `0` to `1`. */
38
+ strength?: number;
39
+ }
40
+ /** Ambient occlusion's values, as the GUI's Ambient occlusion folder lists them. */
41
+ export interface AmbientOcclusionProps {
34
42
  /**
35
43
  * Whether ambient occlusion runs at all.
36
44
  *
37
45
  * A switch rather than a capability: the term also turns itself off for good on a context that
38
46
  * cannot give it a depth texture, and there is nothing here to say about that.
39
47
  */
40
- ambientOcclusion?: boolean;
41
- /** How far ambient occlusion looks for an occluder, in plan units. */
42
- aoRadius?: number;
43
- /** How far ambient occlusion blends an occluded fragment toward the shade, from `0` to `1`. */
44
- aoStrength?: number;
48
+ enabled?: boolean;
49
+ /** How far it looks for an occluder, in plan units. */
50
+ radius?: number;
51
+ /** How far it blends an occluded fragment toward the shade, from `0` to `1`. */
52
+ strength?: number;
53
+ }
54
+ /** The studio HDRI's part of the rig: every value set. */
55
+ 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. */
59
+ rotationDegrees: number;
60
+ }
61
+ /** The sun shadow's part of the rig: every value set. */
62
+ export interface SunShadowSettings {
63
+ /** Whether the shadow-only sun casts shadow-mapped shadows. */
64
+ enabled: boolean;
65
+ /** The sun's heading, counterclockwise on screen from the plan's `+x`. */
66
+ headingDegrees: number;
67
+ /** The sun's height above the horizon. */
68
+ elevationDegrees: number;
69
+ /** How far a roof or the floor in full shadow blends toward the shadow color, `0` to `1`. */
70
+ strength: number;
45
71
  }
46
72
  /**
47
73
  * The light rig, as the debug GUI edits it.
@@ -66,6 +92,10 @@ export interface LightSettings {
66
92
  groundColor: string;
67
93
  /** Directional color, warm against the cool sky so lit faces separate by temperature too. */
68
94
  directionalColor: string;
95
+ /** The studio HDRI. */
96
+ environment: EnvironmentSettings;
97
+ /** The fixed sun's shadow. */
98
+ sunShadow: SunShadowSettings;
69
99
  }
70
100
  /**
71
101
  * Scene lighting: a hemisphere fill along the plan's up axis, and a warm directional light at a
@@ -2,11 +2,18 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
2
2
  import { degToRad } from '@expofp/geometry';
3
3
  import { useFrame, useThree } from '@react-three/fiber';
4
4
  import { useEffect, useLayoutEffect, useRef, useState } from 'react';
5
- import { Color, Vector3, } from 'three';
5
+ import { Color, Matrix4, Vector3, } from 'three';
6
6
  import { useSpace } from '../../space/Space';
7
+ import { createLogger } from '../../utils/logging';
7
8
  import { clamp } from '../../utils/math';
9
+ import { writeContactStrength } from '../materials/effects/contact-shadow';
8
10
  import { useSceneEffects } from '../materials/effects/effects-context';
11
+ import { applySunShadowCatcher, SHADOW_FROM_VIEW, SUN_SHADOW_STRENGTH, } from '../materials/effects/sun-shadow';
12
+ import { setDefaultModelOpacity } from '../models/model-opacity';
9
13
  import { useLightingGui } from './lighting-gui';
14
+ import { hasLitMaterial, loadStudioEnvironment, markEnvironmentPending, orientEnvironment, STUDIO_HDRI_URL, } from './studio-environment';
15
+ import { aimSun, CATCHER_ELEVATION, CATCHER_RENDER_ORDER, enableShadowMaps, fitShadowCamera, hasVisibleCaster, SHADOW_MAP_SIZE, SHADOW_RADIUS, } from './sun-shadow-map';
16
+ const logger = createLogger('lighting');
10
17
  /**
11
18
  * Scene lighting: a hemisphere fill along the plan's up axis, and a warm directional light at a
12
19
  * fixed pitch on the camera's heading. The one intensity control is `contrast`, and `Lighting`
@@ -29,11 +36,14 @@ import { useLightingGui } from './lighting-gui';
29
36
  * @returns The two lights, and the directional light's target.
30
37
  */
31
38
  export function Lighting(props) {
32
- const { contrast, skyColor, groundColor, directionalColor } = props;
39
+ const { contrast, skyColor, groundColor, directionalColor, shadowColor, modelOpacity } = props;
33
40
  // Down to the primitives here rather than in the effect below, so the effect runs when a value
34
- // really moved. A caller writing `lighting={{ shadow: {...} }}` inline hands a fresh object every
35
- // render, and an object in the dependency list would re-apply and redraw on each of them.
36
- const { color: shadowColor, contactDistance, contactStrength, ambientOcclusion, aoRadius, aoStrength, } = props.shadow ?? {};
41
+ // really moved. A caller writing `lighting={{ sunShadow: {...} }}` inline hands a fresh object
42
+ // every render, and an object in the dependency list would re-apply and redraw on each of them.
43
+ const { share: environmentShare, rotationDegrees: environmentRotation } = props.environment ?? {};
44
+ const { enabled: sunEnabled, headingDegrees: sunHeading, elevationDegrees: sunElevation, strength: sunStrength, } = props.sunShadow ?? {};
45
+ const { enabled: contactEnabled, distance: contactDistance, strength: contactStrength, } = props.contactShadow ?? {};
46
+ const { enabled: occlusionEnabled, radius: occlusionRadius, strength: occlusionStrength, } = props.ambientOcclusion ?? {};
37
47
  const fillRef = useRef(null);
38
48
  const directionalRef = useRef(null);
39
49
  const targetRef = useRef(null);
@@ -42,26 +52,121 @@ export function Lighting(props) {
42
52
  const invalidate = useThree((state) => state.invalidate);
43
53
  // `useState` rather than `useRef` so the render body may read it, the way `useDimPatch` holds its
44
54
  // patch.
45
- const [settings] = useState(() => ({ ...LIGHT_DEFAULTS }));
55
+ const [settings] = useState(copyDefaults);
46
56
  // What each light's color was last set from, so a hex string is parsed on change, not per frame.
47
57
  const appliedRef = useRef({ sky: '', ground: '', directional: '' });
58
+ const catcherRef = useRef(null);
59
+ const sunRef = useRef(null);
60
+ const get = useThree((state) => state.get);
61
+ const [studio, setStudio] = useState(null);
48
62
  useLayoutEffect(() => {
49
63
  directionalRef.current.target = targetRef.current;
64
+ sunRef.current.target = targetRef.current;
50
65
  }, []);
66
+ // The studio HDRI, prefiltered once, plus its irradiance for the roof pin. It loads once the scene
67
+ // holds a lit material, so a plan of flat 2D content skips the download.
68
+ const [wantsEnvironment, setWantsEnvironment] = useState(false);
69
+ useEffect(() => {
70
+ if (!wantsEnvironment)
71
+ return undefined;
72
+ let disposed = false;
73
+ let loaded = null;
74
+ // Read by the story screenshot helper, which waits for the HDRI as it waits for a frame.
75
+ markEnvironmentPending(get().scene, true);
76
+ loadStudioEnvironment(get().gl, STUDIO_HDRI_URL).then((environment) => {
77
+ if (disposed) {
78
+ environment.texture.dispose();
79
+ return;
80
+ }
81
+ loaded = environment;
82
+ // Still pending: the frame that applies it clears the flag. A frame asked for here could run
83
+ // before React commits the new state, draw without the HDRI, and read as settled.
84
+ setStudio(environment);
85
+ }, (error) => {
86
+ markEnvironmentPending(get().scene, false);
87
+ logger.warn('failed to load the studio HDRI: %O', error);
88
+ });
89
+ return () => {
90
+ disposed = true;
91
+ const { scene } = get();
92
+ markEnvironmentPending(scene, false);
93
+ if (scene.environment && scene.environment === loaded?.texture)
94
+ scene.environment = null;
95
+ loaded?.texture.dispose();
96
+ };
97
+ }, [get, invalidate, wantsEnvironment]);
98
+ // The frame that applies the HDRI, asked for once React has committed it.
99
+ useEffect(() => {
100
+ if (studio)
101
+ invalidate();
102
+ }, [studio, invalidate]);
103
+ // Turns the renderer's shadow maps on; each light opts in with `castShadow`.
104
+ useEffect(() => {
105
+ enableShadowMaps(get());
106
+ }, [get]);
107
+ // The lookup matrix needs the camera as this frame draws it, and camera-controls moves the
108
+ // camera in a frame callback of its own that may run after ours. Three calls this hook on the
109
+ // scene after every frame callback and after it updates the camera, just before it draws.
110
+ useEffect(() => {
111
+ const { scene } = get();
112
+ // Called with the scene as `this`, the receiver it expects.
113
+ // eslint-disable-next-line @typescript-eslint/unbound-method
114
+ const previous = scene.onBeforeRender;
115
+ scene.onBeforeRender = (renderer, drawnScene, camera, ...rest) => {
116
+ previous.call(scene, renderer, drawnScene, camera, ...rest);
117
+ const sun = sunRef.current;
118
+ if (!sun)
119
+ return;
120
+ // The sun casts while some model can; the shadow map and the floor catcher exist only then. Decided here, before three counts the lights that cast for this frame.
121
+ const casting = settings.sunShadow.enabled && hasVisibleCaster(scene);
122
+ sun.castShadow = casting;
123
+ catcherRef.current.visible = casting;
124
+ if (!casting)
125
+ return;
126
+ // Fitted here, after camera-controls has moved the camera, so a fast zoom is measured with the
127
+ // camera this frame draws with.
128
+ fitShadowCamera(sun, scene, space, catcherRef.current, camera);
129
+ sun.shadow.updateMatrices(sun);
130
+ _cameraWorld.copy(camera.matrixWorldInverse).invert();
131
+ SHADOW_FROM_VIEW.value.multiplyMatrices(sun.shadow.matrix, _cameraWorld);
132
+ };
133
+ return () => {
134
+ scene.onBeforeRender = previous;
135
+ };
136
+ }, [get, space, settings]);
51
137
  // The one place a prop reaches the two mutable objects the frame and the shaders read. Both are
52
138
  // written through a function of this module rather than inline, because the React Compiler treats
53
139
  // what a hook returned as frozen for the closure's own body — the discipline `useOccluder` and
54
140
  // `OcclusionPasses` keep for their own writes.
55
141
  useEffect(() => {
56
- applyLightValues(settings, { contrast, skyColor, groundColor, directionalColor });
142
+ applyLightValues(settings, {
143
+ contrast,
144
+ skyColor,
145
+ groundColor,
146
+ directionalColor,
147
+ environment: { share: environmentShare, rotationDegrees: environmentRotation },
148
+ sunShadow: {
149
+ enabled: sunEnabled,
150
+ headingDegrees: sunHeading,
151
+ elevationDegrees: sunElevation,
152
+ strength: sunStrength,
153
+ },
154
+ });
57
155
  applyShadowValues(effects, {
58
- color: shadowColor,
59
- contactDistance,
60
- contactStrength,
61
- ambientOcclusion,
62
- aoRadius,
63
- aoStrength,
156
+ shadowColor,
157
+ contactShadow: {
158
+ enabled: contactEnabled,
159
+ distance: contactDistance,
160
+ strength: contactStrength,
161
+ },
162
+ ambientOcclusion: {
163
+ enabled: occlusionEnabled,
164
+ radius: occlusionRadius,
165
+ strength: occlusionStrength,
166
+ },
64
167
  });
168
+ if (modelOpacity !== undefined)
169
+ setDefaultModelOpacity(modelOpacity);
65
170
  // Nothing here re-renders and nothing here draws: the frame reads the rig and the shaders read
66
171
  // the uniforms, so a change needs a frame asking for it.
67
172
  invalidate();
@@ -73,12 +178,20 @@ export function Lighting(props) {
73
178
  skyColor,
74
179
  groundColor,
75
180
  directionalColor,
181
+ environmentShare,
182
+ environmentRotation,
183
+ sunEnabled,
184
+ sunHeading,
185
+ sunElevation,
186
+ sunStrength,
76
187
  shadowColor,
188
+ modelOpacity,
189
+ contactEnabled,
77
190
  contactDistance,
78
191
  contactStrength,
79
- ambientOcclusion,
80
- aoRadius,
81
- aoStrength,
192
+ occlusionEnabled,
193
+ occlusionRadius,
194
+ occlusionStrength,
82
195
  ]);
83
196
  // Built here because `Lighting` is mounted once per scene and owns the visual rig. A no-op while
84
197
  // the debug UI is off.
@@ -87,6 +200,13 @@ export function Lighting(props) {
87
200
  useFrame((state) => {
88
201
  const fill = fillRef.current;
89
202
  const directional = directionalRef.current;
203
+ const scene = state.scene;
204
+ if (!wantsEnvironment && hasLitMaterial(scene)) {
205
+ // Marked here, in the frame that decides, so the scene reads as unsettled from this frame on,
206
+ // through the effect that starts the load.
207
+ markEnvironmentPending(scene, true);
208
+ setWantsEnvironment(true);
209
+ }
90
210
  aimDirectionalLight(state.camera, space, settings, directional.position);
91
211
  // The plan's up axis, as a point whose world position lands back on it — which is what three
92
212
  // reads a hemisphere light's sky axis from. Recomputed rather than memoized, because the space
@@ -106,11 +226,56 @@ export function Lighting(props) {
106
226
  // Defensive only: the slider never leaves `0`–`1`, but a value set out of band must not hand an
107
227
  // over-range contrast to a ceiling that assumes one.
108
228
  const contrast = clamp(settings.contrast, 0, 1);
109
- const { hemisphereIntensity, directionalIntensity } = intensitiesFromContrast(contrast, pitch, fill.color, fill.groundColor, directional.color);
229
+ // The HDRI's share comes off the roof's budget first; the rig fills what is left.
230
+ const share = studio ? clamp(settings.environment.share, 0, 1) : 0;
231
+ const environmentIntensity = studio ? share / peakChannel(studio.up) : 0;
232
+ const env = {
233
+ intensity: environmentIntensity,
234
+ up: studio?.up ?? BLACK,
235
+ // The HDRI's light on a wall averaged over every heading, so the rig stays the same as the
236
+ // camera turns and a low, bright sun in the HDRI leaves room for the directional light.
237
+ wall: studio?.wall ?? BLACK,
238
+ };
239
+ const { hemisphereIntensity, directionalIntensity } = intensitiesFromContrast(contrast, pitch, fill.color, fill.groundColor, directional.color, env);
110
240
  fill.intensity = hemisphereIntensity * Math.PI;
111
241
  directional.intensity = directionalIntensity * Math.PI;
242
+ const environment = studio && share > 0 ? studio.texture : null;
243
+ if (scene.environment !== environment)
244
+ scene.environment = environment;
245
+ if (studio)
246
+ markEnvironmentPending(scene, false);
247
+ scene.environmentIntensity = environmentIntensity;
248
+ orientEnvironment(space, settings.environment.rotationDegrees, scene.environmentRotation);
249
+ // The camera-relative lights light; the sun only casts.
250
+ const sun = sunRef.current;
251
+ SUN_SHADOW_STRENGTH.value = 0;
252
+ if (settings.sunShadow.enabled) {
253
+ sun.shadow.radius = SHADOW_RADIUS;
254
+ sun.shadow.mapSize.set(SHADOW_MAP_SIZE, SHADOW_MAP_SIZE);
255
+ aimSun(settings, sun.position);
256
+ catcherRef.current.material.color.copy(effects.shadowColor.value);
257
+ // How far a roof and the floor in full shadow blend toward the shadow color: a fixed value, so
258
+ // the sun's shadow stays the same as the camera and its camera-relative rig turn.
259
+ const strength = clamp(settings.sunShadow.strength, 0, 1);
260
+ catcherRef.current.material.opacity = strength;
261
+ // Divided by the sun's height so a roof loses exactly `strength`; the shader weighs each face
262
+ // by how squarely it faces the sun, and a face turned away loses nothing.
263
+ SUN_SHADOW_STRENGTH.value =
264
+ strength / Math.max(Math.sin(degToRad(settings.sunShadow.elevationDegrees)), 0.05);
265
+ }
112
266
  });
113
- return (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: fillRef, color: LIGHT_DEFAULTS.skyColor, groundColor: LIGHT_DEFAULTS.groundColor, intensity: DEFAULT_INTENSITIES.hemisphereIntensity * Math.PI }), _jsx("directionalLight", { ref: directionalRef, color: LIGHT_DEFAULTS.directionalColor, intensity: DEFAULT_INTENSITIES.directionalIntensity * Math.PI }), _jsx("object3D", { ref: targetRef })] }));
267
+ return (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: fillRef, color: LIGHT_DEFAULTS.skyColor, groundColor: LIGHT_DEFAULTS.groundColor, intensity: DEFAULT_INTENSITIES.hemisphereIntensity * Math.PI }), _jsx("directionalLight", { ref: directionalRef, color: LIGHT_DEFAULTS.directionalColor, intensity: DEFAULT_INTENSITIES.directionalIntensity * Math.PI }), _jsx("object3D", { ref: targetRef }), _jsx("directionalLight", { ref: sunRef, intensity: 0 }), _jsxs("mesh", { ref: catcherRef, position: [0, 0, CATCHER_ELEVATION], receiveShadow: true, renderOrder: CATCHER_RENDER_ORDER, raycast: () => null, visible: false, children: [_jsx("planeGeometry", { args: [1, 1] }), _jsx("shadowMaterial", { color: "#000000", depthWrite: false, onBeforeCompile: applySunShadowCatcher })] })] }));
268
+ }
269
+ /**
270
+ * A fresh rig from the defaults, its nested groups copied too, so each mount owns its own.
271
+ * @returns The rig.
272
+ */
273
+ function copyDefaults() {
274
+ return {
275
+ ...LIGHT_DEFAULTS,
276
+ environment: { ...LIGHT_DEFAULTS.environment },
277
+ sunShadow: { ...LIGHT_DEFAULTS.sunShadow },
278
+ };
114
279
  }
115
280
  /**
116
281
  * Writes the rig values a caller gave, and leaves every value the caller omitted as it stands.
@@ -129,6 +294,21 @@ function applyLightValues(settings, values) {
129
294
  settings.groundColor = values.groundColor;
130
295
  if (values.directionalColor !== undefined)
131
296
  settings.directionalColor = values.directionalColor;
297
+ const environment = values.environment ?? {};
298
+ if (environment.share !== undefined)
299
+ settings.environment.share = environment.share;
300
+ if (environment.rotationDegrees !== undefined) {
301
+ settings.environment.rotationDegrees = environment.rotationDegrees;
302
+ }
303
+ const sun = values.sunShadow ?? {};
304
+ if (sun.enabled !== undefined)
305
+ settings.sunShadow.enabled = sun.enabled;
306
+ if (sun.headingDegrees !== undefined)
307
+ settings.sunShadow.headingDegrees = sun.headingDegrees;
308
+ if (sun.elevationDegrees !== undefined)
309
+ settings.sunShadow.elevationDegrees = sun.elevationDegrees;
310
+ if (sun.strength !== undefined)
311
+ settings.sunShadow.strength = sun.strength;
132
312
  }
133
313
  /**
134
314
  * Writes the darkening values a caller gave onto the scene's own effect state, and leaves every
@@ -144,20 +324,25 @@ function applyLightValues(settings, values) {
144
324
  * @param values - What the caller gave, any subset of it.
145
325
  */
146
326
  function applyShadowValues(effects, values) {
147
- if (values.color !== undefined) {
148
- effects.shadowHex = values.color;
149
- effects.shadowColor.value.set(values.color);
327
+ if (values.shadowColor !== undefined) {
328
+ effects.shadowHex = values.shadowColor;
329
+ effects.shadowColor.value.set(values.shadowColor);
150
330
  }
151
- if (values.contactDistance !== undefined)
152
- effects.shadowDistance.value = values.contactDistance;
153
- if (values.contactStrength !== undefined)
154
- effects.shadowStrength.value = values.contactStrength;
155
- if (values.ambientOcclusion !== undefined)
156
- effects.enabled = values.ambientOcclusion;
157
- if (values.aoRadius !== undefined)
158
- effects.radius = values.aoRadius;
159
- if (values.aoStrength !== undefined)
160
- effects.aoStrength.value = values.aoStrength;
331
+ const contact = values.contactShadow ?? {};
332
+ if (contact.enabled !== undefined)
333
+ effects.contactEnabled = contact.enabled;
334
+ if (contact.distance !== undefined)
335
+ effects.shadowDistance.value = contact.distance;
336
+ if (contact.strength !== undefined)
337
+ effects.contactStrength = contact.strength;
338
+ writeContactStrength(effects);
339
+ const occlusion = values.ambientOcclusion ?? {};
340
+ if (occlusion.enabled !== undefined)
341
+ effects.enabled = occlusion.enabled;
342
+ if (occlusion.radius !== undefined)
343
+ effects.radius = occlusion.radius;
344
+ if (occlusion.strength !== undefined)
345
+ effects.aoStrength.value = occlusion.strength;
161
346
  }
162
347
  /**
163
348
  * Aims the directional light, in the plan's own space, where up is `+z`.
@@ -252,24 +437,26 @@ function applyColor(target, hex, applied, key) {
252
437
  * @param sky - The hemisphere's sky color, linear.
253
438
  * @param ground - The hemisphere's ground color, linear.
254
439
  * @param directionalColor - The directional light's color, linear.
440
+ * @param env - The HDRI's share of the light, and what it gives a roof and a wall.
255
441
  * @returns The directional intensity ceiling, in `π` units.
256
442
  */
257
- function maxDirectional(pitchRadians, sky, ground, directionalColor) {
443
+ function maxDirectional(pitchRadians, sky, ground, directionalColor, env = NO_ENVIRONMENT) {
258
444
  const cos = Math.cos(pitchRadians);
259
- let peakDirectionalColor = 0;
445
+ // Where `h` reaches `0` once the HDRI took its own share of each channel.
446
+ let ceiling = Infinity;
260
447
  for (const channel of CHANNELS) {
261
- peakDirectionalColor = Math.max(peakDirectionalColor, directionalColor[channel]);
448
+ // Guards a grazing or past-vertical pitch, where `cos` is at or below `0`: without this the
449
+ // interval's top would be infinite, negative, or both.
450
+ const left = Math.max(1 - env.intensity * env.up[channel], 0);
451
+ ceiling = Math.min(ceiling, left / Math.max(directionalColor[channel] * cos, MIN_PEAK));
262
452
  }
263
- // Guards a grazing or past-vertical pitch, where `cos` is at or below `0`: without this the
264
- // interval's top would be infinite, negative, or both.
265
- const ceiling = 1 / Math.max(peakDirectionalColor * cos, MIN_PEAK);
266
- if (litWallPeak(ceiling, pitchRadians, sky, ground, directionalColor) < 1)
453
+ if (litWallPeak(ceiling, pitchRadians, sky, ground, directionalColor, env) < 1)
267
454
  return ceiling;
268
455
  let low = 0;
269
456
  let high = ceiling;
270
457
  for (let iteration = 0; iteration < BISECTION_ITERATIONS; iteration++) {
271
458
  const mid = (low + high) / 2;
272
- if (litWallPeak(mid, pitchRadians, sky, ground, directionalColor) < 1)
459
+ if (litWallPeak(mid, pitchRadians, sky, ground, directionalColor, env) < 1)
273
460
  low = mid;
274
461
  else
275
462
  high = mid;
@@ -294,11 +481,12 @@ function maxDirectional(pitchRadians, sky, ground, directionalColor) {
294
481
  * @param sky - The hemisphere's sky color, linear.
295
482
  * @param ground - The hemisphere's ground color, linear.
296
483
  * @param directionalColor - The directional light's color, linear.
484
+ * @param env - The HDRI's share of the light, and what it gives a roof and a wall.
297
485
  * @returns The hemisphere and directional intensities, in `π` units.
298
486
  */
299
- function intensitiesFromContrast(contrast, pitchRadians, sky, ground, directionalColor) {
300
- const directionalIntensity = contrast * maxDirectional(pitchRadians, sky, ground, directionalColor);
301
- const hemisphereIntensity = hemisphereForDirectional(directionalIntensity, pitchRadians, sky, directionalColor);
487
+ function intensitiesFromContrast(contrast, pitchRadians, sky, ground, directionalColor, env = NO_ENVIRONMENT) {
488
+ const directionalIntensity = contrast * maxDirectional(pitchRadians, sky, ground, directionalColor, env);
489
+ const hemisphereIntensity = hemisphereForDirectional(directionalIntensity, pitchRadians, sky, directionalColor, env);
302
490
  return { hemisphereIntensity, directionalIntensity };
303
491
  }
304
492
  /**
@@ -312,9 +500,10 @@ function intensitiesFromContrast(contrast, pitchRadians, sky, ground, directiona
312
500
  * @param pitchRadians - The directional light's angle from the plan's up axis, as aimed.
313
501
  * @param sky - The hemisphere's sky color, linear.
314
502
  * @param directionalColor - The directional light's color, linear.
503
+ * @param env - The HDRI's share of the light, and what it gives a roof and a wall.
315
504
  * @returns The hemisphere intensity, in `π` units.
316
505
  */
317
- function hemisphereForDirectional(directionalIntensity, pitchRadians, sky, directionalColor) {
506
+ function hemisphereForDirectional(directionalIntensity, pitchRadians, sky, directionalColor, env = NO_ENVIRONMENT) {
318
507
  const cos = Math.cos(pitchRadians);
319
508
  let hemisphereIntensity = Infinity;
320
509
  for (const channel of CHANNELS) {
@@ -322,9 +511,13 @@ function hemisphereForDirectional(directionalIntensity, pitchRadians, sky, direc
322
511
  // never carry a meaningful hemisphere contribution anyway, so flooring the divisor costs nothing
323
512
  // real.
324
513
  const skyChannel = Math.max(sky[channel], MIN_SKY);
325
- hemisphereIntensity = Math.min(hemisphereIntensity, (1 - directionalIntensity * directionalColor[channel] * cos) / skyChannel);
514
+ hemisphereIntensity = Math.min(hemisphereIntensity, (1 -
515
+ directionalIntensity * directionalColor[channel] * cos -
516
+ env.intensity * env.up[channel]) /
517
+ skyChannel);
326
518
  }
327
- return hemisphereIntensity;
519
+ // An HDRI share of `1` leaves the hemisphere at `0`, its floor.
520
+ return Math.max(hemisphereIntensity, 0);
328
521
  }
329
522
  /**
330
523
  * The peak channel of a wall facing the light, given a directional intensity already chosen and the
@@ -334,15 +527,18 @@ function hemisphereForDirectional(directionalIntensity, pitchRadians, sky, direc
334
527
  * @param sky - The hemisphere's sky color, linear.
335
528
  * @param ground - The hemisphere's ground color, linear.
336
529
  * @param directionalColor - The directional light's color, linear.
530
+ * @param env - The HDRI's share of the light, and what it gives a roof and a wall.
337
531
  * @returns The lit wall's brightest channel.
338
532
  */
339
- function litWallPeak(directionalIntensity, pitchRadians, sky, ground, directionalColor) {
340
- const hemisphereIntensity = hemisphereForDirectional(directionalIntensity, pitchRadians, sky, directionalColor);
533
+ function litWallPeak(directionalIntensity, pitchRadians, sky, ground, directionalColor, env = NO_ENVIRONMENT) {
534
+ const hemisphereIntensity = hemisphereForDirectional(directionalIntensity, pitchRadians, sky, directionalColor, env);
341
535
  const sin = Math.sin(pitchRadians);
342
536
  let peak = -Infinity;
343
537
  for (const channel of CHANNELS) {
344
538
  const wallMix = (ground[channel] + sky[channel]) / 2;
345
- peak = Math.max(peak, hemisphereIntensity * wallMix + directionalIntensity * directionalColor[channel] * sin);
539
+ peak = Math.max(peak, hemisphereIntensity * wallMix +
540
+ directionalIntensity * directionalColor[channel] * sin +
541
+ env.intensity * env.wall[channel]);
346
542
  }
347
543
  return peak;
348
544
  }
@@ -360,9 +556,23 @@ const LIGHT_DEFAULTS = {
360
556
  skyColor: '#ffffff',
361
557
  groundColor: '#b9c1cc',
362
558
  directionalColor: '#fff3e6',
559
+ environment: {
560
+ share: 0.5,
561
+ rotationDegrees: 180,
562
+ },
563
+ sunShadow: {
564
+ enabled: true,
565
+ // An afternoon sun, low enough for long shadows across the floor.
566
+ headingDegrees: -55,
567
+ elevationDegrees: 48,
568
+ strength: 0.3,
569
+ },
363
570
  };
364
571
  /** The color channels clipping is decided on, one at a time. */
365
572
  const CHANNELS = ['r', 'g', 'b'];
573
+ // Declared before `DEFAULT_INTENSITIES` reads them at module init.
574
+ const BLACK = new Color(0, 0, 0);
575
+ const NO_ENVIRONMENT = { intensity: 0, up: BLACK, wall: BLACK };
366
576
  /** Bisection steps {@link maxDirectional} takes — cheap on a frame, and far past the precision the GUI's own slider step can show. */
367
577
  const BISECTION_ITERATIONS = 20;
368
578
  /**
@@ -382,3 +592,12 @@ const MIN_PEAK = 1e-6;
382
592
  const DEFAULT_INTENSITIES = intensitiesFromContrast(LIGHT_DEFAULTS.contrast, degToRad(LIGHT_DEFAULTS.pitchDegrees), new Color(LIGHT_DEFAULTS.skyColor), new Color(LIGHT_DEFAULTS.groundColor), new Color(LIGHT_DEFAULTS.directionalColor));
383
593
  /** The camera's up axis, reused each frame so aiming allocates nothing. */
384
594
  const _up = new Vector3();
595
+ /**
596
+ * The brightest channel of a color.
597
+ * @param color - The color.
598
+ * @returns Its largest channel, never below `MIN_PEAK`.
599
+ */
600
+ function peakChannel(color) {
601
+ return Math.max(color.r, color.g, color.b, MIN_PEAK);
602
+ }
603
+ const _cameraWorld = new Matrix4();
@@ -6,6 +6,6 @@
6
6
  * derived intensities, the occlusion pipeline's own render targets and the GUI folder stay behind
7
7
  * it.
8
8
  */
9
- export { Lighting, type LightingProps, type ShadowProps } from './Lighting';
9
+ export { type AmbientOcclusionProps, type ContactShadowProps, type EnvironmentProps, Lighting, type LightingProps, type SunShadowProps, } from './Lighting';
10
10
  export { OcclusionPasses } from './OcclusionPasses';
11
11
  //# sourceMappingURL=index.d.ts.map
@@ -6,5 +6,5 @@
6
6
  * derived intensities, the occlusion pipeline's own render targets and the GUI folder stay behind
7
7
  * it.
8
8
  */
9
- export { Lighting } from './Lighting';
9
+ export { Lighting, } from './Lighting';
10
10
  export { OcclusionPasses } from './OcclusionPasses';