@bendyline/molen-client 0.0.13 → 0.0.16

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.
@@ -0,0 +1,151 @@
1
+ import * as THREE from "three";
2
+ //#region src/three/render-bounds.ts
3
+ /**
4
+ * `userData` key of a render group's bounds: a `THREE.Box3` in the frame of the group's parent
5
+ * that contains everything the group draws, now and as its parts move. A group without one is
6
+ * never left out.
7
+ */
8
+ const RENDER_BOUNDS = "renderBounds";
9
+ /** `userData` flag asking a group's owner to work its bounds out again (see `markRenderBoundsChanged`). */
10
+ const RENDER_BOUNDS_STALE = "renderBoundsStale";
11
+ /**
12
+ * `userData` flag an owner sets on its render group when it adds content to it: that content has
13
+ * no world matrices until a walk reaches it, and the renderer may be leaving the group out of the
14
+ * scene's walk. Before a shadow map draws a group it left out, the renderer brings a flagged
15
+ * group's matrices up to date and clears the flag; an owner whose group skips walks while hidden
16
+ * clears it in the walk it does make.
17
+ */
18
+ const RENDER_MATRICES_STALE = "renderMatricesStale";
19
+ /**
20
+ * Tell the render group above `object` that what it draws has changed size: call it after adding
21
+ * or replacing geometry inside streamed content once that content is on show (a landmark's next
22
+ * level of detail arriving, say). The group's owner works its bounds out again before the next
23
+ * frame. Does nothing for an object outside any group with bounds.
24
+ */
25
+ function markRenderBoundsChanged(object) {
26
+ for (let cursor = object; cursor !== null; cursor = cursor.parent) {
27
+ if (cursor.userData["renderBounds"] === void 0) continue;
28
+ cursor.userData[RENDER_BOUNDS_STALE] = true;
29
+ return;
30
+ }
31
+ }
32
+ /** A camera's view volume as the matrix from world to clip space, for `boxOutsideView`. */
33
+ function viewProjection(camera, target) {
34
+ return target.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
35
+ }
36
+ /**
37
+ * Whether a world-space box lies wholly outside a camera's view: every corner beyond the same
38
+ * side of it, or all of them behind a perspective camera. Without `depth` the near and far planes
39
+ * are not tested (ground a camera's far plane cuts is still wanted, and the test then holds for
40
+ * either depth convention). With it, a box wholly nearer than `near` or beyond `far` along the
41
+ * camera's axis is outside too, read in view space: an orthographic shadow map is a box, and
42
+ * ground far along the light's direction lines up with it without being in it. A box across a
43
+ * corner of the view can read as inside when it is not, which only costs the walk it would have
44
+ * saved.
45
+ */
46
+ function boxOutsideView(matrix, min, max, depth) {
47
+ const m = matrix.elements;
48
+ let left = true, right = true, below = true, above = true, behind = true;
49
+ if (depth !== void 0) {
50
+ const v = depth.view.elements;
51
+ let nearer = true, farther = true;
52
+ for (let corner = 0; corner < 8 && (nearer || farther); corner++) {
53
+ const along = -(v[2] * (corner & 1 ? max.x : min.x) + v[6] * (corner & 2 ? max.y : min.y) + v[10] * (corner & 4 ? max.z : min.z) + v[14]);
54
+ if (along >= depth.near) nearer = false;
55
+ if (along <= depth.far) farther = false;
56
+ }
57
+ if (nearer || farther) return true;
58
+ }
59
+ for (let corner = 0; corner < 8; corner++) {
60
+ const x = corner & 1 ? max.x : min.x, y = corner & 2 ? max.y : min.y, z = corner & 4 ? max.z : min.z;
61
+ const cx = m[0] * x + m[4] * y + m[8] * z + m[12], cy = m[1] * x + m[5] * y + m[9] * z + m[13], cw = m[3] * x + m[7] * y + m[11] * z + m[15];
62
+ if (cx >= -cw) left = false;
63
+ if (cx <= cw) right = false;
64
+ if (cy >= -cw) below = false;
65
+ if (cy <= cw) above = false;
66
+ if (cw > 0) behind = false;
67
+ if (!(left || right || below || above || behind)) return false;
68
+ }
69
+ return true;
70
+ }
71
+ const corner = new THREE.Vector3();
72
+ const local = new THREE.Box3();
73
+ const IDENTITY = new THREE.Matrix4();
74
+ /**
75
+ * Grow `bounds` (in `frame`'s own coordinates) to hold everything `object` draws: each mesh's
76
+ * bounding box where it has one already (an instanced mesh's own, over its instances), and
77
+ * otherwise the box round its bounding sphere, which three works out for its own culling anyway.
78
+ * Nothing is measured from vertices that three would not measure too: a box computed here for
79
+ * every building's geometry was a pass over a dense tile's half a million vertices, 5 ms of the
80
+ * job that published it. An object marked `userData.dynamicTransform` may turn about its own
81
+ * origin, so it and what is under it count as the sphere they can sweep there; one that travels
82
+ * needs its owner to state bounds for the whole of its way. Local matrices are read as they stand
83
+ * (static content has them frozen), so the object need not have been drawn or even attached.
84
+ * `padding` is added round each part.
85
+ */
86
+ function expandRenderBounds(bounds, object, frame, padding = 0) {
87
+ const chain = [];
88
+ for (let cursor = object; cursor !== null && cursor !== frame; cursor = cursor.parent) chain.push(cursor);
89
+ const placement = new THREE.Matrix4();
90
+ for (let i = chain.length - 1; i >= 0; i--) {
91
+ const part = chain[i];
92
+ if (part.matrixAutoUpdate) part.updateMatrix();
93
+ placement.multiply(part.matrix);
94
+ }
95
+ expand(bounds, object, placement, padding, false, 0);
96
+ return bounds;
97
+ }
98
+ /** One placement matrix per depth of the walk, reused: a tile's content is thousands of parts. */
99
+ const placements = [];
100
+ /** `placement` is the object's own, in the frame `bounds` is measured in. */
101
+ function expand(bounds, object, placement, padding, swept, depth) {
102
+ if (!swept && object.userData.dynamicTransform === true) {
103
+ const reach = new THREE.Box3();
104
+ expand(reach, object, IDENTITY, 0, true, depth);
105
+ if (reach.isEmpty()) return;
106
+ let radius = 0;
107
+ for (let i = 0; i < 8; i++) {
108
+ corner.set(i & 1 ? reach.max.x : reach.min.x, i & 2 ? reach.max.y : reach.min.y, i & 4 ? reach.max.z : reach.min.z);
109
+ radius = Math.max(radius, corner.length());
110
+ }
111
+ radius = radius * placement.getMaxScaleOnAxis() + padding;
112
+ corner.setFromMatrixPosition(placement);
113
+ bounds.expandByPoint(local.min.copy(corner).addScalar(-radius));
114
+ bounds.expandByPoint(local.max.copy(corner).addScalar(radius));
115
+ return;
116
+ }
117
+ const mesh = object;
118
+ if (mesh.isMesh || object.isLine || object.isPoints) {
119
+ const instanced = object;
120
+ const source = instanced.isInstancedMesh ? instanced : mesh.geometry;
121
+ const box = source.boundingBox;
122
+ if (box !== null) {
123
+ if (!box.isEmpty()) {
124
+ local.copy(box).applyMatrix4(placement);
125
+ if (padding > 0) local.expandByScalar(padding);
126
+ bounds.union(local);
127
+ }
128
+ } else {
129
+ if (source.boundingSphere === null) source.computeBoundingSphere();
130
+ const sphere = source.boundingSphere;
131
+ if (sphere !== null && sphere.radius >= 0) {
132
+ const radius = sphere.radius * placement.getMaxScaleOnAxis() + padding;
133
+ corner.copy(sphere.center).applyMatrix4(placement);
134
+ bounds.expandByPoint(local.min.copy(corner).addScalar(-radius));
135
+ bounds.expandByPoint(local.max.copy(corner).addScalar(radius));
136
+ }
137
+ }
138
+ }
139
+ if (object.children.length === 0) return;
140
+ let next = placements[depth];
141
+ if (next === void 0) {
142
+ next = new THREE.Matrix4();
143
+ placements[depth] = next;
144
+ }
145
+ for (const child of object.children) {
146
+ if (child.matrixAutoUpdate) child.updateMatrix();
147
+ expand(bounds, child, next.multiplyMatrices(placement, child.matrix), padding, swept, depth + 1);
148
+ }
149
+ }
150
+ //#endregion
151
+ export { expandRenderBounds as a, boxOutsideView as i, RENDER_BOUNDS_STALE as n, markRenderBoundsChanged as o, RENDER_MATRICES_STALE as r, viewProjection as s, RENDER_BOUNDS as t };
@@ -1,3 +1,4 @@
1
+ import { a as SnowCoverUniforms } from "./snow-cover-tEG1uO98.mjs";
1
2
  import { EarthObserver, Quat, ResolvedWeather, SkyData, SkyPalette, SkyTime, Vec3, WeatherData } from "@bendyline/molen-schema";
2
3
  import * as THREE from "three";
3
4
  import { WebGPURenderer } from "three/webgpu";
@@ -9,7 +10,8 @@ interface AdmissionOptions {
9
10
  signal?: AbortSignal;
10
11
  label?: string;
11
12
  /**
12
- * Background jobs run only in frame budget that no normal job is waiting for. Urgent jobs run
13
+ * Background jobs run in frame budget that no normal job is waiting for, and once one has waited
14
+ * `backgroundWaitMs` it takes a turn after every `backgroundShare` other jobs. Urgent jobs run
13
15
  * before normal ones, in their own order: small work the view is visibly waiting on, such as
14
16
  * terrain ground. Sustained urgent traffic shares service with waiting normal work.
15
17
  */
@@ -28,11 +30,37 @@ interface AdmissionSample {
28
30
  }
29
31
  interface SceneAdmission {
30
32
  run<T>(task: () => T, options?: AdmissionOptions): Promise<T>;
33
+ /** Jobs waiting, where the queue can say, so optional work can hold off behind a backlog. */
34
+ readonly pending?: number;
35
+ }
36
+ /**
37
+ * A larger frame budget for work that is backing up. Once the oldest waiting job (not a
38
+ * background one) has waited `afterMs`, the frame's time and byte budgets grow with its wait and
39
+ * reach these at twice that; a limit left out, or below the ordinary one, stays as it is. A fixed
40
+ * small budget protects the frame rate of a view that keeps up and starves one that does not: a
41
+ * city streaming in under an aircraft asked for more than twice the work 2 ms a frame could
42
+ * publish, each job waited 3 s (21 s at worst) for each of the several turns a tile's layer
43
+ * takes, and the ground ahead stayed bare while the queue used a twentieth of the main thread.
44
+ */
45
+ interface AdmissionBacklog {
46
+ afterMs: number;
47
+ maxMilliseconds?: number;
48
+ maxBytes?: number;
31
49
  }
32
50
  interface FrameAdmissionOptions {
33
51
  maxMilliseconds?: number;
34
52
  maxBytes?: number;
35
53
  maxJobs?: number;
54
+ /** See `AdmissionBacklog`; none by default. */
55
+ backlog?: AdmissionBacklog | undefined;
56
+ /**
57
+ * How long a background job waits (ms, default 750) before the lane takes turns with the others,
58
+ * and how many other jobs run between its turns (default 8). In flight normal work never runs
59
+ * out, and what waited behind it (texture upgrades, the levels an object is not showing yet)
60
+ * arrived seconds late: a second on average over a town, five at worst.
61
+ */
62
+ backgroundWaitMs?: number;
63
+ backgroundShare?: number;
36
64
  now?: () => number;
37
65
  schedule?: (callback: () => void) => void;
38
66
  onSample?: (sample: AdmissionSample) => void;
@@ -45,21 +73,41 @@ declare class FrameAdmissionQueue implements SceneAdmission {
45
73
  private scheduled;
46
74
  private disposed;
47
75
  private paused;
76
+ /** Milliseconds past its budget the last flush ran, repaid from the frames after it. */
77
+ private overrunMs;
78
+ /** When the last flush finished, so a repaying frame knows how long it was. */
79
+ private lastFlushEnd;
80
+ /** The last flush left work waiting, so the time since it ended is a frame, not idle time. */
81
+ private continuing;
82
+ /** Frame lengths outside the queue while work waited, newest last, at most SLOW_FRAMES. */
83
+ private readonly recentFrames;
48
84
  private readonly clock;
49
85
  private readonly schedule;
50
86
  private maxMs;
51
87
  private maxBytes;
52
88
  private maxJobs;
89
+ private backlog;
53
90
  private urgentStreak;
54
91
  private orderedStreak;
92
+ /** Jobs from the other lanes since the background lane last ran one. */
93
+ private foregroundStreak;
94
+ private readonly backgroundWaitMs;
95
+ private readonly backgroundShare;
55
96
  /** Recent work time per label (ms, smoothed): what the next job of that kind will likely take. */
56
97
  private readonly expected;
57
98
  constructor(options?: FrameAdmissionOptions);
58
99
  /**
59
100
  * Change the per-frame budget from the next frame on; omitted limits keep their values. A host
60
- * can admit more when frames have time to spare (an adaptive quality tier, say).
101
+ * can admit more when frames have time to spare (an adaptive quality tier, say). `backlog` is
102
+ * replaced when the key is present: `undefined` takes the backlog budget away.
61
103
  */
62
- setLimits(limits: Pick<FrameAdmissionOptions, "maxMilliseconds" | "maxBytes" | "maxJobs">): void;
104
+ setLimits(limits: Pick<FrameAdmissionOptions, "maxMilliseconds" | "maxBytes" | "maxJobs" | "backlog">): void;
105
+ /**
106
+ * How far into its backlog budget the queue is, 0 to 1: by how long the oldest job outside the
107
+ * background lane has waited. Urgent jobs sit ahead of the others, each kind in arrival order
108
+ * but for the ordered jobs taken from among them, so the oldest is the first of either kind.
109
+ */
110
+ private pressure;
63
111
  run<T>(task: () => T, options?: AdmissionOptions): Promise<T>;
64
112
  /**
65
113
  * Callers keep the promise (preparation caches do, keyed by long-lived resources); the job holds
@@ -78,8 +126,27 @@ declare class FrameAdmissionQueue implements SceneAdmission {
78
126
  /** Hold queued uploads/preparation while the view is inactive; keep resources for resume. */
79
127
  setPaused(paused: boolean): void;
80
128
  private request;
81
- /** One frame's budget. Exposed for hosts with a manual frame loop and deterministic tests. */
129
+ /**
130
+ * One frame's budget. Exposed for hosts with a manual frame loop and deterministic tests.
131
+ *
132
+ * A job cannot be split, so one can take several frames' budget by itself, and a queue of them
133
+ * would hold every frame at that length however small the budget. A frame that overruns repays
134
+ * the excess from the frames after it, so the budget holds on average: a 20 ms shader build
135
+ * every third frame, rather than every frame at half the frame rate, for the same throughput.
136
+ *
137
+ * The budget is a share of a frame at 60 a second. A frame that comes later than that repays
138
+ * the same share of its own length: under software rendering a frame takes 200 ms or more, and
139
+ * a job that waits on the GPU once is charged for a whole such frame, so repaying 2 ms a frame
140
+ * left the queue idle for minutes. At 60 frames a second and faster nothing changes. Sustained
141
+ * frames that slow also run that share of themselves (see SLOW_FRAME_MS).
142
+ */
82
143
  flush(): void;
144
+ /**
145
+ * This frame's work allowance: the budget (`maxMs`, the ordinary one or what a backlog has grown
146
+ * it to), or for sustained software-rendering frames the same share of the shortest recent one.
147
+ * One long frame (a hitch) changes nothing.
148
+ */
149
+ private frameBudget;
83
150
  dispose(): void;
84
151
  }
85
152
  //#endregion
@@ -201,6 +268,7 @@ declare class SkyVisual {
201
268
  readonly data: SkyData;
202
269
  private readonly dome;
203
270
  private readonly sun;
271
+ private readonly glare;
204
272
  private readonly moon;
205
273
  private readonly stars;
206
274
  private catalog;
@@ -236,6 +304,10 @@ declare class SkyVisual {
236
304
  prepareCamera(camera: THREE.Camera): void;
237
305
  private updateDome;
238
306
  private updateBody;
307
+ private sunColor;
308
+ private updateGlare;
309
+ /** The drawn dome's color toward a unit direction, interpolated across its vertex grid. */
310
+ private domeColor;
239
311
  /**
240
312
  * Replace the star catalog, e.g. once a catalog loaded from a content pack arrives. `undefined`
241
313
  * removes the stars. Takes effect on the next update.
@@ -473,6 +545,16 @@ declare class WeatherVisual {
473
545
  dispose(): void;
474
546
  }
475
547
  //#endregion
548
+ //#region src/three/far-shadow.d.ts
549
+ interface FarShadowInfo {
550
+ /** Half-width of the map as drawn, meters. */
551
+ radius: number;
552
+ /** Times the map has been drawn. */
553
+ draws: number;
554
+ /** Main-thread time of its last drawing, ms. */
555
+ lastDrawMs: number;
556
+ }
557
+ //#endregion
476
558
  //#region src/three/gpu-frame-timer.d.ts
477
559
  interface GpuFrameTimerOptions {
478
560
  /** Maximum outstanding queries, including an active measurement. Default 4. */
@@ -503,6 +585,15 @@ interface ShadowFocus {
503
585
  center: readonly [number, number, number];
504
586
  /** Minimum half-width of the shadowed square, meters. Rounded up for a stable texel grid. */
505
587
  radius: number;
588
+ /**
589
+ * A second, wider map around `center` (absolute world coordinates) covering at least
590
+ * ±`radius` meters, for the scenery named by `Renderer.setFarShadowCasters`: surfaces past the
591
+ * focused map read it instead of ending in sunlight. WebGL.
592
+ */
593
+ far?: {
594
+ center: readonly [number, number, number];
595
+ radius: number;
596
+ };
506
597
  }
507
598
  //#endregion
508
599
  //#region src/three/webgpu-ambient-occlusion.d.ts
@@ -565,6 +656,8 @@ type ThreeRenderer = THREE.WebGLRenderer | WebGPURenderer;
565
656
  interface CloudBackend {
566
657
  material(uniforms: CloudUniforms, textures: CloudTextures): THREE.Material;
567
658
  installShadows(uniforms: CloudShadowUniforms): void;
659
+ /** Lying snow on marked materials (WebGPU: webgpu-snow-cover.ts). */
660
+ installSnowCover(uniforms: SnowCoverUniforms): void;
568
661
  }
569
662
  interface InitializedRenderer {
570
663
  three: ThreeRenderer;
@@ -572,6 +665,8 @@ interface InitializedRenderer {
572
665
  optimizer?: WebGpuSceneOptimizer;
573
666
  reflectionFilter?: SkyReflectionFilter;
574
667
  clouds?: CloudBackend;
668
+ /** The WebGPU adapter is a fallback (software) adapter; see Renderer.softwareRasterizer. */
669
+ softwareAdapter?: boolean;
575
670
  }
576
671
  interface RendererOptions {
577
672
  /** Shared procedural sky/ground reflections for PBR materials. Default false; Earth viewers enable it. */
@@ -592,6 +687,12 @@ interface RendererOptions {
592
687
  backendProbeTimeoutMs?: number;
593
688
  /** Persistent instance buffers and managed tile command caches. Defaults to true on WebGPU. */
594
689
  optimizeWebGpu?: boolean;
690
+ /**
691
+ * WebGL: leave render groups that state their bounds (see `createRenderGroup`) out of each
692
+ * scene walk they cannot be seen in, and out of each shadow map they cannot cast into. Default
693
+ * true; false walks every group every frame, for comparison.
694
+ */
695
+ cullRenderGroups?: boolean;
595
696
  /** Device loss requires a new viewer/canvas. Auto fallback applies during initialization. */
596
697
  onDeviceLost?: (reason: string) => void;
597
698
  canvas?: HTMLCanvasElement | OffscreenCanvas;
@@ -671,7 +772,21 @@ declare class Renderer {
671
772
  /** Per material, one prepared mesh of each kind it draws; see `prepareMaterialChange`. */
672
773
  private readonly materialMeshes;
673
774
  /** The scene's visible lights for warm-up builds, gathered once between rendered frames. */
775
+ /**
776
+ * WebGL render groups, for `cullRenderGroups`. Held weakly: a group is made before its owner
777
+ * attaches it (a tile's, several frames before) and may never be, and one its owner has let
778
+ * go of must not be kept alive here.
779
+ */
780
+ private readonly renderGroups;
781
+ /** Groups left out of the scene walk under way, to show again when it ends. */
782
+ private readonly culledGroups;
783
+ private cullGroups;
784
+ private releaseShadowCulling;
674
785
  private preparationLights;
786
+ /** Every light the last walk of the scene found on show, and when it was (see `sceneLights`). */
787
+ private foundLights;
788
+ private foundLightsChildren;
789
+ private foundLightsAt;
675
790
  /**
676
791
  * Per mesh, builds of the materials it swaps to itself (`null`: prepared with the mesh); see
677
792
  * `prepareVariants`.
@@ -688,6 +803,15 @@ declare class Renderer {
688
803
  readonly backend: RendererBackend;
689
804
  private fallback;
690
805
  get fallbackReason(): string | undefined;
806
+ private software;
807
+ /**
808
+ * Whether this device draws through a software rasterizer: SwiftShader (headless and
809
+ * blocklisted-GPU Chromium), Mesa's llvmpipe or lavapipe, Windows' Basic Render Driver, or a
810
+ * WebGPU fallback adapter. Every pixel and vertex then costs CPU time, so a host that sizes its
811
+ * work to the device starts at its lowest tier. Read once, from the WebGL context's unmasked
812
+ * renderer string (false where the browser hides it) or the WebGPU adapter's fallback flag.
813
+ */
814
+ get softwareRasterizer(): boolean;
691
815
  readonly scene: THREE.Scene;
692
816
  /** World-space objects live here so the renderer can rebase them near the camera. */
693
817
  readonly worldRoot: THREE.Group;
@@ -729,6 +853,8 @@ declare class Renderer {
729
853
  /** Cloud textures and the cloud-shadow uniforms every lit shader reads, for the renderer's life. */
730
854
  private readonly cloudTextures;
731
855
  private readonly cloudShadows;
856
+ /** The weather's lying snow, read by every material marked with `enableSnowCover`. */
857
+ private readonly snowCover;
732
858
  private readonly cloudBackend;
733
859
  private releaseCloudShadows;
734
860
  private cloudQualityLevel;
@@ -742,6 +868,10 @@ declare class Renderer {
742
868
  private shadowFocus;
743
869
  private readonly shadowCenter;
744
870
  private readonly shadowDirection;
871
+ /** The sun's far shadow map (WebGL); see setFarShadowCasters. */
872
+ private farShadow;
873
+ private readonly farShadowCenter;
874
+ private readonly farShadowDirection;
745
875
  /** Active clear-sky visual and sampled ephemeris, when environment.sky is configured. */
746
876
  get sky(): SkyVisual | undefined;
747
877
  /**
@@ -751,6 +881,24 @@ declare class Renderer {
751
881
  */
752
882
  setShadowFocus(focus: ShadowFocus | undefined): void;
753
883
  /**
884
+ * The scenery that does not move (a terrain stream's object: ground, buildings, trees), for the
885
+ * sun's far shadow map. With it and a focus that names a `far` square, surfaces past the
886
+ * focused map are shadowed from a second, wider map instead of ending in sunlight: over a
887
+ * city the focused map ends a few hundred meters out, and buildings gained their shadows as
888
+ * it reached them. Only what is under `root` casts into it, and it is redrawn when the camera
889
+ * has left its middle, when the sun has moved and about once a second for scenery that has
890
+ * arrived, so a moving caster would leave its shadow behind. WebGL; `undefined` turns it off.
891
+ */
892
+ setFarShadowCasters(root: THREE.Object3D | undefined): void;
893
+ /** The far shadow map as last drawn, or `undefined` while there is none. */
894
+ get farShadowInfo(): FarShadowInfo | undefined;
895
+ /**
896
+ * Meters one texel of the sun's shadow map covers as of the last frame, or `undefined` while sun
897
+ * shadows are off or parked. A focus over a wide view coarsens it: hosts use it to keep a subject
898
+ * the map cannot resolve out of the shadow pass (`AircraftVisual.updateShadows`).
899
+ */
900
+ get shadowTexelSize(): number | undefined;
901
+ /**
754
902
  * Turn sun shadows on at a map resolution, or off, without rebuilding the environment. Once a
755
903
  * light has cast shadows, 'off' stops redrawing its map and fades it out, so every lit shader
756
904
  * keeps the shadow inputs it was built with: a host that turns shadows on once before its first
@@ -886,7 +1034,16 @@ declare class Renderer {
886
1034
  * mid-frame (130 ms in flight).
887
1035
  */
888
1036
  private compileWebGl;
889
- /** The scene's visible lights, gathered once between rendered frames for warm-up builds. */
1037
+ /**
1038
+ * The scene's visible lights, for warm-up builds, as of this frame. Finding them is a walk of
1039
+ * the whole visible scene, and made once between rendered frames that was 1.2 ms of every frame
1040
+ * that prepared anything over a streamed city (two lights among nine thousand objects), which
1041
+ * in flight is all of them. So the lights found stand for `LIGHTS_REFRESH_MS`, or until the
1042
+ * scene's own children change, and each frame only checks which of them are still on show. A
1043
+ * light that appears deeper in the scene counts from the next walk: until then a warm-up is
1044
+ * built, and remembered, for the lights before it, so it is prepared again rather than taken
1045
+ * for ready.
1046
+ */
890
1047
  private sceneLights;
891
1048
  /**
892
1049
  * What a lit program is built for besides its material and mesh: the scene's lights and which
@@ -910,6 +1067,24 @@ declare class Renderer {
910
1067
  private hideReflectedAmbient;
911
1068
  private renderScene;
912
1069
  /**
1070
+ * Hide, for the scene walk about to start, every render group whose bounds lie wholly outside
1071
+ * the camera's view: three then skips it and everything under it when it brings world matrices
1072
+ * up to date, updates levels of detail and gathers what to draw, none of which can draw
1073
+ * anything from it. Shown again when the render ends (see `renderScene`), so nothing outside the
1074
+ * render sees a group hidden. Shadow maps are walked on their own terms (`installShadowCulling`).
1075
+ */
1076
+ private cullOutOfView;
1077
+ /**
1078
+ * Walk each shadow map's casters without the render groups that cannot cast into it. A map is
1079
+ * drawn from its light, so what counts is the light's own view, not the camera's: groups hidden
1080
+ * for the camera come back for a light that reaches them (with their world matrices and levels
1081
+ * of detail brought up to date, which the scene's walk skipped), and groups the camera sees stay
1082
+ * out of a map that ends short of them. The sun's focused map covers a few hundred meters of a
1083
+ * view tens of kilometers deep, and three walked every object of that view for it. Lights
1084
+ * other than directional ones keep every group, as before.
1085
+ */
1086
+ private installShadowCulling;
1087
+ /**
913
1088
  * Once WebGL sun shadows draw, a frame of degenerate casters (one plain and one instanced mesh
914
1089
  * per side): the shadow pass builds a depth program for each kind of caster the first time it
915
1090
  * draws one, and the first double-sided caster in view held a mid-flight frame 10 ms. The
@@ -933,7 +1108,12 @@ declare class Renderer {
933
1108
  suspendAmbientOcclusion(suspended: boolean): void;
934
1109
  /** The occlusion pass for the current camera, building one in the background when needed. */
935
1110
  private currentOcclusion;
936
- /** Use for independent terrain/content chunks. WebGPU caches eligible opaque draw commands. */
1111
+ /**
1112
+ * Use for independent terrain/content chunks. WebGPU caches eligible opaque draw commands.
1113
+ * WebGL leaves a group out of the scene walks it cannot be seen in, once its owner states its
1114
+ * bounds in `userData.renderBounds` (see `RENDER_BOUNDS`) and keeps them true as its content
1115
+ * changes (`expandRenderBounds`, `markRenderBoundsChanged`): see `cullRenderGroups`.
1116
+ */
937
1117
  createRenderGroup(): THREE.Group;
938
1118
  /** Last completed visible frame, excluding offscreen resource preparation. */
939
1119
  stats(): {
@@ -945,4 +1125,4 @@ declare class Renderer {
945
1125
  dispose(): void;
946
1126
  }
947
1127
  //#endregion
948
- export { SkyReflectionState as A, defaultSkyPalette as C, skyTimeMs as D, evaluateEarthSky as E, AdmissionSample as F, FrameAdmissionOptions as I, FrameAdmissionQueue as L, createWebGlSkyReflectionFilter as M, reflectionStateFromLights as N, starDirection as O, AdmissionOptions as P, SceneAdmission as R, SkyVisualOptions as S, EarthSkyState as T, WeatherVisualOptions as _, RendererBackendPreference as a, SkyStar as b, TopDownOrtho as c, ShadowFocus as d, ShadowQuality as f, WeatherVisual as g, createGpuFrameTimer as h, RendererBackend as i, SkyReflections as j, SkyReflectionFilter as k, nextWorldOrigin as l, GpuFrameTimerOptions as m, CameraPose as n, RendererOptions as o, GpuFrameTimer as p, Renderer as r, ThreeRenderer as s, AutoWorldOriginOptions as t, orthoFrustum as u, CloudQuality as v, CelestialPosition as w, SkyVisual as x, SkyFrame as y };
1128
+ export { SkyReflectionFilter as A, SceneAdmission as B, SkyVisualOptions as C, evaluateEarthSky as D, EarthSkyState as E, AdmissionBacklog as F, AdmissionOptions as I, AdmissionSample as L, SkyReflections as M, createWebGlSkyReflectionFilter as N, skyTimeMs as O, reflectionStateFromLights as P, FrameAdmissionOptions as R, SkyVisual as S, CelestialPosition as T, WeatherVisual as _, RendererBackendPreference as a, SkyFrame as b, TopDownOrtho as c, ShadowFocus as d, ShadowQuality as f, FarShadowInfo as g, createGpuFrameTimer as h, RendererBackend as i, SkyReflectionState as j, starDirection as k, nextWorldOrigin as l, GpuFrameTimerOptions as m, CameraPose as n, RendererOptions as o, GpuFrameTimer as p, Renderer as r, ThreeRenderer as s, AutoWorldOriginOptions as t, orthoFrustum as u, WeatherVisualOptions as v, defaultSkyPalette as w, SkyStar as x, CloudQuality as y, FrameAdmissionQueue as z };