@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
@@ -37,11 +37,8 @@ export function useLightingGui(light) {
37
37
  }, [effects, gui, light]);
38
38
  }
39
39
  /**
40
- * The Lighting folder: the light's aim, the two lights' colors, the contrast, and the Occlusion
41
- * folder nested inside it.
42
- *
43
- * `contrast` needs no moving bound the way the intensity ratio it replaced did: its range is `0`–`1`
44
- * at every pitch, so there is nothing here to keep in sync with the pitch controller.
40
+ * The Lighting folder: the light's aim, the sun, the studio's turn, and one folder per darkening
41
+ * term.
45
42
  * @param gui - The GUI to add the folder to.
46
43
  * @param light - The rig each controller binds to.
47
44
  * @param effects - The mounted scene's effect state, which the nested folder binds to.
@@ -49,22 +46,26 @@ export function useLightingGui(light) {
49
46
  */
50
47
  function addLightingFolder(gui, light, effects) {
51
48
  const folder = gui.addFolder('Lighting');
49
+ // The sun's heading and elevation aim the light unless it follows the camera. The host owns them
50
+ // (the `lighting` prop), so they have no control here.
51
+ const follow = folder.add(light, 'followCamera').name('sun follows camera');
52
52
  const track = folder.add(light, 'trackPitch').name('track camera pitch');
53
53
  const pitch = folder.add(light, 'pitchDegrees', 0, 89, 1).name('pitch°');
54
- track.onChange((on) => toggle(pitch, !on));
55
- toggle(pitch, !light.trackPitch);
56
- folder.addColor(light, 'skyColor').name('sky color');
57
- folder.addColor(light, 'groundColor').name('ground color');
58
- folder.addColor(light, 'directionalColor').name('directional color');
59
- folder.add(light, 'contrast', 0, 1, 0.01).name('contrast');
54
+ const showAim = () => {
55
+ toggle(track, light.followCamera);
56
+ toggle(pitch, light.followCamera && !light.trackPitch);
57
+ };
58
+ follow.onChange(showAim);
59
+ track.onChange(showAim);
60
+ showAim();
61
+ folder.add(light, 'sun', 0, 1, 0.01).name('sun');
60
62
  // The studio environment, then the shared shade and one folder per darkening term.
61
- folder.add(light.environment, 'share', 0, 1, 0.01).name('environment share');
62
63
  folder.add(light.environment, 'rotationDegrees', -180, 180, 1).name('environment rotation°');
63
64
  folder
64
65
  .addColor(effects, 'shadowHex')
65
66
  .name('shadow color')
66
- // lil-gui writes display sRGB and three holds the working space, so `Color.set` converts. Every
67
- // term reads this one object, so the shade moves for all of them or for none.
67
+ // lil-gui writes display sRGB and three holds the working space, so `Color.set` converts. The
68
+ // contact shadow and ambient occlusion read this one object, so the shade moves for both.
68
69
  .onChange((hex) => effects.shadowColor.value.set(hex));
69
70
  // The opacity of every model whose def sets none.
70
71
  const models = { opacity: getDefaultModelOpacity() };
@@ -73,23 +74,36 @@ function addLightingFolder(gui, light, effects) {
73
74
  .name('model opacity')
74
75
  .onChange((value) => setDefaultModelOpacity(value));
75
76
  addSunShadow(folder, light.sunShadow);
77
+ addSideShade(folder, effects);
76
78
  addContactShadow(folder, effects);
77
79
  addAmbientOcclusion(folder, effects);
78
80
  return folder;
79
81
  }
80
82
  /**
81
83
  * Adds the sun shadow's folder. Every controller binds the rig's own `sunShadow` group, which the
82
- * frame reads.
84
+ * frame reads. The sun's heading and elevation are not here: the host owns where the sun stands, so
85
+ * a control here would fight the `lighting` prop it writes.
83
86
  * @param folder - The Lighting folder.
84
87
  * @param sun - The rig's sun shadow group.
85
88
  */
86
89
  function addSunShadow(folder, sun) {
87
90
  const sunFolder = folder.addFolder('Sun shadows');
88
91
  sunFolder.add(sun, 'enabled').name('enabled');
89
- sunFolder.add(sun, 'headingDegrees', -180, 180, 1).name('heading°');
90
- sunFolder.add(sun, 'elevationDegrees', 5, 90, 1).name('elevation°');
91
92
  sunFolder.add(sun, 'strength', 0, 1, 0.01).name('strength');
92
93
  }
94
+ /**
95
+ * Adds the side shade's folder: how much darker a wall is than a roof, and its tint.
96
+ * @param folder - The Lighting folder.
97
+ * @param effects - The mounted scene's effect state.
98
+ */
99
+ function addSideShade(folder, effects) {
100
+ const side = folder.addFolder('Side shade');
101
+ side.add(effects.sideShade, 'value', 0, 0.8, 0.01).name('shade');
102
+ side
103
+ .addColor(effects, 'sideTintHex')
104
+ .name('tint')
105
+ .onChange((hex) => effects.sideTint.value.set(hex));
106
+ }
93
107
  /**
94
108
  * Adds the contact shadow's folder. The shader has no switch of its own, so the switch and the
95
109
  * strength both go through {@link writeContactStrength}, which parks the depth at `0` while off.
@@ -102,7 +116,7 @@ function addContactShadow(folder, effects) {
102
116
  .add(effects, 'contactEnabled')
103
117
  .name('enabled')
104
118
  .onChange(() => writeContactStrength(effects));
105
- contact.add(effects.shadowDistance, 'value', 1, 5, 0.1).name('distance');
119
+ contact.add(effects.shadowDistance, 'value', 1, 10, 0.01).name('distance');
106
120
  contact
107
121
  .add(effects, 'contactStrength', 0, 1, 0.01)
108
122
  .name('strength')
@@ -1,47 +1,36 @@
1
- import { Color, type Euler, type Scene, type Texture, type WebGLRenderer } from 'three';
1
+ import { type Euler, type Scene, type Texture, type WebGLRenderer } from 'three';
2
2
  import { type Space } from '../../space/Space';
3
3
  /**
4
- * The studio HDRI that lights models and solid shapes: loading it, measuring the light it gives a
5
- * roof and a wall, and turning it about the plan's up axis.
4
+ * The studio environment that lights models and solid shapes: three's `RoomEnvironment`, the studio
5
+ * the efp3d sandbox lights its plan with, the light it gives a roof and a wall, and its turn about the
6
+ * plan's up axis.
6
7
  *
7
- * `Lighting` consumes what this measures: the HDRI's share of a roof's light comes off the rig's
8
- * budget first, and the hemisphere and directional lights fill the rest.
8
+ * `Lighting` consumes what this measures: the studio fills a roof's light up to its color after the
9
+ * sun's share.
9
10
  */
10
- /** The HDRI's light on a surface, in `π` units per unit of `scene.environmentIntensity`. */
11
- export interface EnvironmentTerm {
12
- /** `scene.environmentIntensity`. */
13
- intensity: number;
14
- /** An up-facing surface's light per unit intensity, per channel. */
15
- up: Color;
16
- /** A wall's light per unit intensity, per channel, averaged over every heading. */
17
- wall: Color;
18
- }
19
- /** The prefiltered HDRI and the light it gives a roof and a wall. */
11
+ /** The prefiltered studio and the light it gives a roof. */
20
12
  export interface StudioEnvironment {
21
- /** The prefiltered HDRI, for `scene.environment`. */
13
+ /** The prefiltered studio, for `scene.environment`. */
22
14
  texture: Texture;
23
- /** The HDRI's light on a roof, per unit intensity. */
24
- up: Color;
25
- /** The HDRI's light on a wall, per unit intensity, averaged over every heading. */
26
- wall: Color;
15
+ /** The studio's light on a roof, per unit of `scene.environmentIntensity`, in `π` units. */
16
+ up: number;
27
17
  }
28
18
  /**
29
- * Loads the studio HDRI, prefilters it, and measures its light.
19
+ * Renders the studio and prefilters it for this renderer.
30
20
  * @param renderer - The renderer PMREM draws with.
31
- * @param url - The HDRI's URL.
32
21
  * @returns The texture and its light terms.
33
22
  */
34
- export declare function loadStudioEnvironment(renderer: WebGLRenderer, url: string): Promise<StudioEnvironment>;
23
+ export declare function createStudioEnvironment(renderer: WebGLRenderer): StudioEnvironment;
35
24
  /**
36
- * Whether any visible mesh draws with a lit material, the kind the HDRI reaches.
25
+ * Whether any visible mesh draws with a lit material, the kind the environment reaches.
37
26
  * @param scene - The scene.
38
27
  * @returns Whether one does.
39
28
  */
40
29
  export declare function hasLitMaterial(scene: Scene): boolean;
41
30
  /**
42
- * Stands the HDRI upright on the plan and turns it about the plan's up axis.
31
+ * Stands the studio upright on the plan and turns it about the plan's up axis.
43
32
  *
44
- * three samples an equirect with `+y` up, and the plan has `+z` up, so a world direction goes to the
33
+ * three samples an environment with `+y` up, and the plan has `+z` up, so a world direction goes to the
45
34
  * plan and then through the models' own plan → glTF axis swap, which puts the plan's up on `+y`. The
46
35
  * shader samples `transpose(R) · worldDir`, with `R` from `environmentRotation`, so `R` is the
47
36
  * transpose of `turn · GLTF_FROM_PLAN · (world → plan)`.
@@ -50,21 +39,4 @@ export declare function hasLitMaterial(scene: Scene): boolean;
50
39
  * @param target - The scene's `environmentRotation`, written in place.
51
40
  */
52
41
  export declare function orientEnvironment(space: Space, rotationDegrees: number, target: Euler): void;
53
- /**
54
- * Records on the scene whether its studio HDRI is still loading.
55
- * @param scene - The scene.
56
- * @param pending - Whether the load is in flight.
57
- */
58
- export declare function markEnvironmentPending(scene: Scene, pending: boolean): void;
59
- /**
60
- * The `scene.userData` key that is `true` while the studio HDRI loads. The story screenshot helper
61
- * waits on it the way it waits on a pending frame, since the HDRI relights every lit surface when it
62
- * lands.
63
- */
64
- export declare const ENVIRONMENT_PENDING = "efpEnvironmentPending";
65
- /**
66
- * Poly Haven's "Ninomaru Teien" (CC0): a garden with trees and sky on every side, so a facade or a
67
- * pool reflects something with contrast at any bearing.
68
- */
69
- export declare const STUDIO_HDRI_URL: string;
70
42
  //# sourceMappingURL=studio-environment.d.ts.map
@@ -1,35 +1,22 @@
1
1
  import { degToRad } from '@expofp/geometry';
2
- import { Color, DataTexture, EquirectangularReflectionMapping, FloatType, LinearFilter, LinearSRGBColorSpace, Matrix4, PMREMGenerator, RGBAFormat, SphericalHarmonics3, Vector3, } from 'three';
3
- import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
2
+ import { Matrix4, PMREMGenerator, } from 'three';
3
+ import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
4
4
  import { GLTF_FROM_PLAN } from '../models/model-container';
5
- // Emitted as a file of its own beside the chunk; a library build inlines every other asset as
6
- // base64. `vite/client` types the import.
7
- import forestHdriUrl from './hdri/forest.exr?url&no-inline';
8
5
  /**
9
- * Loads the studio HDRI, prefilters it, and measures its light.
6
+ * Renders the studio and prefilters it for this renderer.
10
7
  * @param renderer - The renderer PMREM draws with.
11
- * @param url - The HDRI's URL.
12
8
  * @returns The texture and its light terms.
13
9
  */
14
- export async function loadStudioEnvironment(renderer, url) {
15
- const { data, width, height, up, wall } = await loadHdri(url);
16
- // The pixels are shared; the texture, its upload and the prefiltered result belong to this
17
- // renderer.
18
- const equirect = new DataTexture(data, width, height, RGBAFormat, FloatType);
19
- equirect.mapping = EquirectangularReflectionMapping;
20
- equirect.colorSpace = LinearSRGBColorSpace;
21
- equirect.minFilter = LinearFilter;
22
- equirect.magFilter = LinearFilter;
23
- equirect.generateMipmaps = false;
24
- equirect.needsUpdate = true;
10
+ export function createStudioEnvironment(renderer) {
11
+ const room = new RoomEnvironment();
25
12
  const pmrem = new PMREMGenerator(renderer);
26
- const texture = pmrem.fromEquirectangular(equirect).texture;
27
- equirect.dispose();
13
+ const texture = pmrem.fromScene(room, STUDIO_BLUR).texture;
28
14
  pmrem.dispose();
29
- return { texture, up, wall };
15
+ room.dispose();
16
+ return { texture, up: STUDIO_UP };
30
17
  }
31
18
  /**
32
- * Whether any visible mesh draws with a lit material, the kind the HDRI reaches.
19
+ * Whether any visible mesh draws with a lit material, the kind the environment reaches.
33
20
  * @param scene - The scene.
34
21
  * @returns Whether one does.
35
22
  */
@@ -39,15 +26,14 @@ export function hasLitMaterial(scene) {
39
26
  if (found || !object.isMesh)
40
27
  return;
41
28
  const materials = [].concat(object.material);
42
- found = materials.some((material) => material.isMeshStandardMaterial ||
43
- material.isMeshLambertMaterial);
29
+ found = materials.some((material) => material.isMeshStandardMaterial);
44
30
  });
45
31
  return found;
46
32
  }
47
33
  /**
48
- * Stands the HDRI upright on the plan and turns it about the plan's up axis.
34
+ * Stands the studio upright on the plan and turns it about the plan's up axis.
49
35
  *
50
- * three samples an equirect with `+y` up, and the plan has `+z` up, so a world direction goes to the
36
+ * three samples an environment with `+y` up, and the plan has `+z` up, so a world direction goes to the
51
37
  * plan and then through the models' own plan → glTF axis swap, which puts the plan's up on `+y`. The
52
38
  * shader samples `transpose(R) · worldDir`, with `R` from `environmentRotation`, so `R` is the
53
39
  * transpose of `turn · GLTF_FROM_PLAN · (world → plan)`.
@@ -61,107 +47,13 @@ export function orientEnvironment(space, rotationDegrees, target) {
61
47
  _lookup.premultiply(_turn).transpose();
62
48
  target.setFromRotationMatrix(_lookup);
63
49
  }
50
+ /** The prefilter's blur, in radians: the efp3d sandbox's own. */
51
+ const STUDIO_BLUR = 0.04;
64
52
  /**
65
- * Records on the scene whether its studio HDRI is still loading.
66
- * @param scene - The scene.
67
- * @param pending - Whether the load is in flight.
68
- */
69
- export function markEnvironmentPending(scene, pending) {
70
- scene.userData[ENVIRONMENT_PENDING] = pending;
71
- }
72
- /**
73
- * Fetches, decodes and measures an HDRI once per URL. Decoding and the spherical-harmonics
74
- * projection run on the CPU, so every later scene on the page reuses them.
75
- * @param url - The HDRI's URL.
76
- * @returns Its pixels and light terms.
77
- */
78
- function loadHdri(url) {
79
- let pending = hdris.get(url);
80
- if (!pending) {
81
- pending = decodeHdri(url);
82
- pending.catch(() => hdris.delete(url));
83
- hdris.set(url, pending);
84
- }
85
- return pending;
86
- }
87
- /**
88
- * Decodes an HDRI and measures its light.
89
- * @param url - The HDRI's URL.
90
- * @returns Its pixels and light terms.
91
- */
92
- async function decodeHdri(url) {
93
- const equirect = await new EXRLoader().setDataType(FloatType).loadAsync(url);
94
- const { data, width, height } = equirect.image;
95
- const sh = projectEquirect(data, width, height);
96
- // Irradiance is `π · L` for a uniform radiance `L`, and three's IBL diffuse is `albedo · L`, so
97
- // `E / π` is the HDRI's light in the rig's own `π` units. Up is `+y` in the equirect's frame.
98
- const up = irradiance(sh, _axis.set(0, 1, 0), new Color());
99
- const wall = new Color(0, 0, 0);
100
- for (let step = 0; step < WALL_HEADINGS; step++) {
101
- const angle = (step / WALL_HEADINGS) * Math.PI * 2;
102
- irradiance(sh, _axis.set(Math.cos(angle), 0, Math.sin(angle)), _color);
103
- wall.add(_color.multiplyScalar(1 / WALL_HEADINGS));
104
- }
105
- return { data, width, height, up, wall };
106
- }
107
- /**
108
- * The irradiance at a normal, divided by `π`.
109
- * @param sh - The projection.
110
- * @param normal - The surface normal, in the equirect's frame.
111
- * @param target - Receives the result.
112
- * @returns `target`.
113
- */
114
- function irradiance(sh, normal, target) {
115
- sh.getIrradianceAt(normal, _irradiance);
116
- return target.setRGB(_irradiance.x, _irradiance.y, _irradiance.z).multiplyScalar(1 / Math.PI);
117
- }
118
- /**
119
- * Projects an equirect onto the first nine spherical harmonics, in three's equirect frame:
120
- * `u = atan2(z, x) / 2π + 0.5`, `v = asin(y) / π + 0.5`, row `0` at `v ≈ 0`.
121
- * @param data - RGBA floats, row by row.
122
- * @param width - Texels per row.
123
- * @param height - Rows.
124
- * @returns The projection.
125
- */
126
- function projectEquirect(data, width, height) {
127
- const sh = new SphericalHarmonics3();
128
- const basis = new Array(9).fill(0);
129
- const texelArea = ((2 * Math.PI) / width) * (Math.PI / height);
130
- for (let row = 0; row < height; row++) {
131
- const elevation = ((row + 0.5) / height - 0.5) * Math.PI;
132
- const weight = Math.cos(elevation) * texelArea;
133
- for (let column = 0; column < width; column++) {
134
- const azimuth = ((column + 0.5) / width - 0.5) * Math.PI * 2;
135
- _axis.set(Math.cos(elevation) * Math.cos(azimuth), Math.sin(elevation), Math.cos(elevation) * Math.sin(azimuth));
136
- SphericalHarmonics3.getBasisAt(_axis, basis);
137
- const index = (row * width + column) * 4;
138
- _color.setRGB(data[index], data[index + 1], data[index + 2]);
139
- for (let k = 0; k < 9; k++) {
140
- sh.coefficients[k].x += _color.r * basis[k] * weight;
141
- sh.coefficients[k].y += _color.g * basis[k] * weight;
142
- sh.coefficients[k].z += _color.b * basis[k] * weight;
143
- }
144
- }
145
- }
146
- return sh;
147
- }
148
- /**
149
- * The `scene.userData` key that is `true` while the studio HDRI loads. The story screenshot helper
150
- * waits on it the way it waits on a pending frame, since the HDRI relights every lit surface when it
151
- * lands.
152
- */
153
- export const ENVIRONMENT_PENDING = 'efpEnvironmentPending';
154
- /**
155
- * Poly Haven's "Ninomaru Teien" (CC0): a garden with trees and sky on every side, so a facade or a
156
- * pool reflects something with contrast at any bearing.
53
+ * The studio's light on a roof, per unit intensity, in `π` units. Measured once, since the studio is
54
+ * fixed: three 0.185's `LightProbeGenerator` on a 256-texel float cube render of `RoomEnvironment`,
55
+ * then `SphericalHarmonics3.getIrradianceAt / π`. The studio is gray, so the channels agree.
157
56
  */
158
- export const STUDIO_HDRI_URL = forestHdriUrl;
159
- /** The headings a wall's light is averaged over. */
160
- const WALL_HEADINGS = 16;
161
- /** Decoded HDRIs, by URL; see {@link loadHdri}. */
162
- const hdris = new Map();
163
- const _axis = new Vector3();
164
- const _color = new Color();
165
- const _irradiance = new Vector3();
57
+ const STUDIO_UP = 1.622;
166
58
  const _lookup = new Matrix4();
167
59
  const _turn = new Matrix4();
@@ -1,22 +1,29 @@
1
1
  import { type Camera, type DirectionalLight, type Mesh, type Scene, Vector3, type WebGLRenderer } from 'three';
2
+ import { BatchedMeshImpl } from '../../core/batch/BatchedMesh';
3
+ import { type InstancedMeshImpl } from '../../core/instanced/InstancedMesh';
2
4
  import { type Space } from '../../space/Space';
3
5
  import { type LightSettings } from './Lighting';
4
6
  /**
5
- * The fixed sun's shadow map: where the sun stands, which area the map covers, and when the map is
6
- * drawn again.
7
+ * The sun's shadow map: where the sun stands, which area the map covers, and when the map is drawn
8
+ * again.
7
9
  *
8
10
  * The map is baked. It is fitted to what the camera sees and redrawn when the sun, the visible
9
11
  * casters or the fitted area change, so camera motion inside the fitted area reuses it. `Lighting`
10
- * mounts the sun and calls {@link fitShadowCamera} from the scene's `onBeforeRender`; the lookup
11
- * lives with the materials, in `effects/sun-shadow`.
12
+ * calls {@link fitShadowCamera} from the scene's `onBeforeRender`; three's own lookup applies the
13
+ * map, with the shadow coordinate from `effects/sun-shadow`.
14
+ *
15
+ * Casters that move every frame draw into a second map instead, which {@link syncMovingSun} gives
16
+ * the same fit and which redraws every frame; {@link routeShadow} picks a caster's map, and
17
+ * `effects/sun-shadow` keeps the darker of the two lookups.
12
18
  */
13
19
  /**
14
- * Aims the shadow-only sun from a heading and an elevation. The heading turns counterclockwise on
15
- * screen from the plan's `+x`; the plan's `+y` points down the screen, hence `-sin`.
20
+ * Aims the sun from a heading and an elevation. The heading turns counterclockwise on screen from
21
+ * the plan's `+x`; the plan's `+y` points down the screen, hence `-sin`.
16
22
  * @param settings - The rig.
17
23
  * @param target - The sun's position, a direction in plan space.
24
+ * @returns `target`, unit length.
18
25
  */
19
- export declare function aimSun(settings: LightSettings, target: Vector3): void;
26
+ export declare function aimSun(settings: LightSettings, target: Vector3): Vector3;
20
27
  /**
21
28
  * Turns shadow maps on, PCF with a blur radius.
22
29
  * @param state - The root state, for the renderer.
@@ -32,9 +39,10 @@ export declare function enableShadowMaps(state: {
32
39
  * 1. {@link readCasters}: what the sun and the visible casters look like this frame.
33
40
  * 2. {@link measureCasters}, when that changed: their extent in the sun's view, which sets the
34
41
  * depth range, and the floor catcher's size.
35
- * 3. {@link fitView}: the area the camera sees, kept while the view stays inside it.
36
- * 4. {@link applyFit}: the shadow camera's frustum and biases, and the redraw.
37
- * @param light - The shadow-only sun.
42
+ * 3. {@link fitView}: the area the camera sees, kept while the view stays inside it, and the map
43
+ * size that area needs.
44
+ * 4. {@link applyFit}: the shadow camera's frustum, biases and spread, the map size, and the redraw.
45
+ * @param light - The sun.
38
46
  * @param scene - The scene, walked for casters.
39
47
  * @param space - The scene's space.
40
48
  * @param catcher - The floor's shadow catcher, sized to the casters.
@@ -44,13 +52,27 @@ export declare function fitShadowCamera(light: DirectionalLight, scene: Scene, s
44
52
  /**
45
53
  * Whether any visible mesh casts the sun's shadow.
46
54
  * @param scene - The scene.
55
+ * @param moving - Counts only casters routed to the moving map when `true`.
47
56
  * @returns Whether one does.
48
57
  */
49
- export declare function hasVisibleCaster(scene: Scene): boolean;
50
- /** The shadow map's width and height, in texels: about 64 MB of depth. */
51
- export declare const SHADOW_MAP_SIZE = 4096;
52
- /** The shadow lookup's spread, in texels. */
53
- export declare const SHADOW_RADIUS = 2;
58
+ export declare function hasVisibleCaster(scene: Scene, moving?: boolean): boolean;
59
+ /**
60
+ * Sends a caster's shadow to one of the two maps. A moving caster draws only into the moving sun's
61
+ * map, which redraws every frame, so the still map does not have to. A still caster left unrouted
62
+ * draws into both, which looks the same and costs a redraw every frame.
63
+ * @param mesh - The caster.
64
+ * @param moving - Whether it moves on its own, frame to frame.
65
+ */
66
+ export declare function routeShadow(mesh: InstancedMeshImpl | BatchedMeshImpl, moving: boolean): void;
67
+ /**
68
+ * Makes `moving` the sun for moving casters: the same direction, fit and filtering as `sun`, so one
69
+ * lookup matrix reads both maps, and a redraw each frame while it casts. Hidden while it does not,
70
+ * so three counts no second light in the lit programs of a plan with nothing moving.
71
+ * @param moving - The moving casters' sun.
72
+ * @param sun - The still sun, already fitted for this frame.
73
+ * @param casting - Whether any moving caster is visible.
74
+ */
75
+ export declare function syncMovingSun(moving: DirectionalLight, sun: DirectionalLight, casting: boolean): void;
54
76
  /**
55
77
  * Just below the floor. 2D content writes no depth, so the catcher draws over the floor, and a
56
78
  * model's own ground, which writes depth, hides it cleanly.
@@ -58,4 +80,6 @@ export declare const SHADOW_RADIUS = 2;
58
80
  export declare const CATCHER_ELEVATION = -0.5;
59
81
  /** The catcher draws after every other transparent object, so it shades whatever floor they drew. */
60
82
  export declare const CATCHER_RENDER_ORDER = 1000000;
83
+ /** The moving casters' shadow map's largest width and height, in texels. */
84
+ export declare const MOVING_SHADOW_MAP_SIZE = 2048;
61
85
  //# sourceMappingURL=sun-shadow-map.d.ts.map