@openglobus/og 1.0.0-rc10 → 1.0.0-rc14

package/lib/Globe.d.ts

@@ -42,6 +42,7 @@ export interface IGlobeParams {
     sun?: {
         active?: boolean;
         stopped?: boolean;
+        localDateTime?: Date | null;
     };
     navigation?: {
         active?: boolean;
@@ -73,6 +74,7 @@ export interface IGlobeParams {
     frameOpacity?: number;
     shadeMode?: ShadeModeInput;
     reverseDepth?: boolean;
+    idleMode?: boolean;
 }
 /**
  * @typedef {Array<number>} LonLatCoordinate
@@ -108,6 +110,7 @@ export interface IGlobeParams {
  * @param {Array.<Layer>} [options.layers] - Planet layers.
  * @param {Extent | ExtentBoundingBox} [options.viewExtent] [options.viewExtent] - Viewable starting extent.
  * @param {boolean} [options.autoActivate=true] - Globe rendering auto activation flag. True is default.
+ * @param {boolean} [options.idleMode=false] - Skips a frame rendering when nothing has been changed. False is default.
  * @param {HTMLElement} [options.attributionContainer] - Container for attribution list.
  * @param {number} [options.maxGridSize=128] = Maximal segment grid size. 128 is default
  * @param {string} [options.fontsSrc] - Fonts collection url.

package/lib/camera/Camera.d.ts

@@ -143,6 +143,13 @@ declare class Camera {
     protected _pb: Vec3;
     protected _peye: Vec3;
     isMoving: boolean;
+    /**
+     * Fires when the camera view or projection has been changed. It is assigned by the renderer
+     * to wake it up from the idle mode.
+     * @public
+     * @type {?function(): void}
+     */
+    onViewChange: (() => void) | null;
     protected _pViewAngle: number;
     protected _pAspect: number;
     protected _pWidth: number;
@@ -233,6 +240,7 @@ declare class Camera {
      * @param {IFlyCartesianParams} [params] - Flight parameters
      */
     flyCartesian(cartesian: Vec3, params?: IFlyCartesianParams): void;
+    protected _startFlying(): void;
     /**
      * Breaks the flight.
      * @public

package/lib/camera/PlanetCamera.d.ts

@@ -128,7 +128,7 @@ declare class PlanetCamera extends Camera {
      * @public
      * @param {LonLat} lonlat - New camera and camera view position.
      * @param {LonLat} [lookLonLat] - Look up coordinates.
-     * @param {Vec3} [up] - Camera UP vector. Default (0,1,0)
+     * @param {Vec3} [up] - Camera UP vector. Defaults to the local surface normal for an explicit look point.
      */
     setLonLat(lonlat: LonLat, lookLonLat?: LonLat, up?: Vec3): void;
     /**

package/lib/control/DebugInfo.d.ts

@@ -16,6 +16,7 @@ export declare class DebugInfo extends Control {
     protected _toggleBtn: ToggleButton;
     protected _dialog: Dialog<null>;
     protected _canvasTiles: CanvasTiles;
+    protected _drawnFrames: number;
     constructor(options?: IDebugInfoParams);
     addWatches(watches: IDebugInfoWatch[]): void;
     addWatch(watch: IDebugInfoWatch): void;

package/lib/control/FreeNavigation.d.ts

@@ -0,0 +1,253 @@
+import type { IControlParams } from "./Control";
+import { Control } from "./Control";
+import type { IMouseState } from "../renderer/RendererEvents";
+import { Navigation } from "./Navigation";
+import type { Vec2 } from "../math/Vec2";
+import { Vec3 } from "../math/Vec3";
+import { type EventsHandler } from "../Events";
+export interface IFreeNavigationParams extends IControlParams {
+    speed?: number;
+    minSpeed?: number;
+    maxSpeed?: number;
+    speedStep?: number;
+    speedFactor?: number;
+    lookSensitivity?: number;
+    rollSpeed?: number;
+    accelerationTime?: number;
+    decelerationTime?: number;
+    pitchLimit?: number;
+    invertY?: boolean;
+    pointerLock?: boolean;
+    toggleKey?: number;
+    showInfo?: boolean;
+}
+export type FreeNavigationEventsList = ["move", "rotate", "speedchange", "activate", "deactivate"];
+/**
+ * Free-flight camera navigation.
+ *
+ * - W/S — move forward/backward
+ * - A/D — strafe left/right
+ * - Space/Ctrl — increase/decrease altitude
+ * - Shift — hold to move without changing the camera height above the ellipsoid
+ * - Q/E — roll
+ * - Mouse — look around
+ * - Mouse wheel — adjust movement speed
+ * - Right mouse button — hold to keep the point under the screen center in the center
+ * - F — activate and deactivate the control, see `toggleKey`
+ *
+ * Yaw follows the local ellipsoid normal, while pitch uses the camera's right vector.
+ * The camera preserves its orientation relative to the local horizon while moving.
+ *
+ * By default, pointer lock allows unrestricted mouse rotation. Pressing Escape releases
+ * the pointer and deactivates the control. Set `pointerLock` to `false` to use regular
+ * mouse movement instead.
+ *
+ * The control conflicts with the {@link Navigation} control, so an active {@link Navigation}
+ * is deactivated while the free navigation is active, and restored back on deactivation.
+ *
+ * @class
+ * @extends {Control}
+ * @param {IFreeNavigationParams} [options] - Free navigation options:
+ * @param {number} [options.speed] - Initial selected movement speed in m/s. Default is 0
+ * @param {number} [options.minSpeed] - Minimal selected movement speed in m/s. Default is -300
+ * @param {number} [options.maxSpeed] - Maximal selected movement speed in m/s. Default is 1000000
+ * @param {number} [options.speedStep] - Mouse wheel speed step near the zero speed in m/s. Default is 1
+ * @param {number} [options.speedFactor] - Relative speed increment per one mouse wheel step. Default is 0.45
+ * @param {number} [options.lookSensitivity] - Camera rotation angle in radians per mouse move pixel
+ * @param {number} [options.rollSpeed] - Q/E roll angular speed in radians per second the smoothed
+ * roll velocity approaches
+ * @param {number} [options.accelerationTime] - Acceleration smoothing time in seconds. Default is 0.6
+ * @param {number} [options.decelerationTime] - Deceleration smoothing time in seconds. Default is 0.4
+ * @param {number} [options.pitchLimit] - Maximal pitch angle above and below the local horizon in radians
+ * @param {boolean} [options.invertY] - Inverts vertical mouse rotation direction. Default is false
+ * @param {boolean} [options.pointerLock] - Locks and hides the mouse pointer. Default is true
+ * @param {number} [options.toggleKey] - Key code which activates and deactivates the control,
+ * it works while the control is inactive as well. Zero disables it. Default is `input.KEY_F`
+ * @param {boolean} [options.showInfo] - Shows the movement speed and the key hint. Default is false
+ * @fires move
+ * @fires rotate
+ * @fires speedchange
+ * @fires activate
+ * @fires deactivate
+ */
+export declare class FreeNavigation extends Control {
+    events: EventsHandler<FreeNavigationEventsList>;
+    minSpeed: number;
+    maxSpeed: number;
+    speedStep: number;
+    speedFactor: number;
+    lookSensitivity: number;
+    rollSpeed: number;
+    accelerationTime: number;
+    decelerationTime: number;
+    pitchLimit: number;
+    invertY: boolean;
+    pointerLock: boolean;
+    toggleKey: number;
+    /**
+     * Current camera velocity in meters per second.
+     * @public
+     * @type {Vec3}
+     */
+    vel: Vec3;
+    /**
+     * Current camera roll angular velocity in radians per second.
+     * @public
+     * @type {number}
+     */
+    rollVel: number;
+    /**
+     * Selected movement speed in meters per second.
+     * @protected
+     * @type {number}
+     */
+    protected _speed: number;
+    protected _moveForward: boolean;
+    protected _moveBackward: boolean;
+    protected _moveLeft: boolean;
+    protected _moveRight: boolean;
+    protected _moveUp: boolean;
+    protected _moveDown: boolean;
+    protected _rollDir: number;
+    protected _dx: number;
+    protected _dy: number;
+    protected _skipPointerMove: boolean;
+    protected _targetPoint: Vec3 | null;
+    protected _targetRequest: number;
+    protected _holdHeight: number | null;
+    protected _lastFrameTime: number;
+    protected _frameDeltaTime: number;
+    protected _infoEl: HTMLElement | null;
+    protected _suspendedNavigation: Navigation[];
+    constructor(options?: IFreeNavigationParams);
+    onadd(): void;
+    oninit(): void;
+    onremove(): void;
+    /**
+     * Activates the control when it is inactive and deactivates it otherwise.
+     * @public
+     */
+    toggle(): void;
+    protected _onToggleKey: () => void;
+    protected _updateInfo(): void;
+    onactivate(): void;
+    ondeactivate(): void;
+    /**
+     * Returns selected movement speed in meters per second.
+     * @public
+     * @return {number} -
+     */
+    get speed(): number;
+    /**
+     * Sets selected movement speed in meters per second.
+     * @public
+     * @param {number} speed - Speed in m/s.
+     */
+    set speed(speed: number);
+    /**
+     * Sets selected movement speed in meters per second, clamped to the min and max speed.
+     * @public
+     * @param {number} speed - Speed in m/s.
+     */
+    setSpeed(speed: number): void;
+    /**
+     * Changes the movement speed by the given number of wheel steps.
+     *
+     * The speed step increases with the current speed. Changes are reversible,
+     * and zero speed is always reachable.
+     * @public
+     * @param {number} steps - Number of the wheel steps, negative decreases the speed.
+     */
+    stepSpeed(steps: number): void;
+    /**
+     * True when the mouse pointer is locked by the control.
+     * @public
+     * @return {boolean} -
+     */
+    isPointerLocked(): boolean;
+    /**
+     * Locks and hides the mouse pointer over the canvas.
+     * @public
+     */
+    requestPointerLock(): void;
+    /**
+     * Releases the mouse pointer.
+     * @public
+     */
+    exitPointerLock(): void;
+    /**
+     * Locked target point in the cartesian coordinates, or null when no target is locked.
+     * @public
+     * @return {Vec3 | null} -
+     */
+    get targetPoint(): Vec3 | null;
+    /**
+     * Locks the target point, so the camera keeps looking at it wherever it moves,
+     * @public
+     * @param {Vec3} [point] - Target point in the cartesian coordinates.
+     */
+    lockTarget(point?: Vec3 | null): void;
+    /**
+     * Releases the locked target point.
+     * @public
+     */
+    unlockTarget(): void;
+    /**
+     * Stops the camera movement and releases the locked target point.
+     * @public
+     */
+    stop(): void;
+    protected onPreDraw(): void;
+    protected _hasInput(): boolean;
+    protected _resetInput(): void;
+    private _onCameraFly;
+    protected _onMouseMove: (e: IMouseState) => void;
+    protected _onLockedMouseMove: (e: MouseEvent) => void;
+    protected _onPointerLockChange: () => void;
+    protected _onLDown: () => void;
+    protected _onRDown: () => void;
+    protected _onRUp: () => void;
+    protected _onKeyEscape: () => void;
+    protected _onMouseLeave: () => void;
+    protected _onMouseWheel: (e: IMouseState) => void;
+    protected _onKeyForward: () => void;
+    protected _onKeyBackward: () => void;
+    protected _onKeyLeft: () => void;
+    protected _onKeyRight: () => void;
+    protected _onKeyUp: () => void;
+    protected _onKeyDown: () => void;
+    protected _onKeyRollLeft: () => void;
+    protected _onKeyRollRight: () => void;
+    protected _getLocalUp(eye: Vec3): Vec3;
+    protected _getTargetPixel(): Vec2;
+    protected _pickTargetPoint(px: Vec2): Vec3 | null;
+    protected _handleTargetLock(): void;
+    protected _handleRotation(): void;
+    /**
+     * Clamps the pitch rotation angle.
+     * @protected
+     * @param {number} angle - Pitch angle in radians.
+     * @param {Vec3} forward - Camera forward vector.
+     * @param {Vec3} right - Camera right vector.
+     * @param {Vec3} localUp - Local reference frame up direction.
+     * @return {number} - Applicable pitch angle in radians.
+     */
+    protected _limitPitch(angle: number, forward: Vec3, right: Vec3, localUp: Vec3): number;
+    /**
+     * Rollls the camera around its forward axis and keeps its angular velocity smoothed.
+     * @protected
+     */
+    protected _handleRoll(): void;
+    protected _orthonormalizeCamera(): void;
+    /**
+     * Moves the camera and keeps its orientation in the local reference frame.
+     * @protected
+     */
+    protected _handleMove(): void;
+    protected _isHeightHold(): boolean;
+    protected _handleHeightHold(): void;
+    protected _suspendNavigation(): void;
+    protected _restoreNavigation(): void;
+    protected _updateFrameDeltaTime(): void;
+    protected get dt(): number;
+}

package/lib/control/Navigation.d.ts

@@ -100,6 +100,12 @@ export declare class Navigation extends Control {
     onactivate(): void;
     ondeactivate(): void;
     protected onPreDraw(): void;
+    /**
+     * Returns true while the inertia has not been damped yet.
+     * @public
+     * @returns {boolean}
+     */
+    isMoving(): boolean;
     _onShiftFree: () => void;
     private _onCameraFly;
     protected _onMouseMove: (e: IMouseState) => void;

package/lib/control/ShowFps.d.ts

@@ -1,10 +1,22 @@
+import { Button } from "../ui/Button";
 import { Control } from "./Control";
 import type { IControlParams } from "./Control";
 /**
- * Frame per second(FPS) display control.
+ * Frames per second(FPS) display control. It looks like a map button in the top right
+ * corner and shows the current frame rate instead of an icon.
+ *
+ * Note that the rate is measured by the control itself and not taken from
+ * {@link Handler#deltaTime}, which is clamped and does not represent the real frame time.
+ * @class
+ * @extends {Control}
  */
 export declare class ShowFps extends Control {
-    constructor(options: IControlParams);
+    protected _btn: Button | null;
+    protected _text: HTMLElement | null;
+    protected _frames: number;
+    protected _measureStart: number;
+    constructor(options?: IControlParams);
     oninit(): void;
-    protected _draw(): void;
+    onremove(): void;
+    protected _draw: () => void;
 }

package/lib/control/Sun.d.ts

@@ -1,22 +1,47 @@
 import { Control } from "./Control";
 import type { IControlParams } from "./Control";
 import { Clock } from "../Clock";
+import type { JulianDate } from "../astro/jd";
 import { Vec3 } from "../math/Vec3";
+import type { PlanetCamera } from "../camera/PlanetCamera";
 interface ISunParams extends IControlParams {
     activationHeight?: number;
     offsetVertical?: number;
     offsetHorizontal?: number;
     stopped?: boolean;
+    localDateTime?: Date | null;
 }
 /**
  * Real Sun geocentric position control that place the Sun on the right place by the Earth.
+ * @class
+ *
+ * @example <caption>Lighting frozen at 21:30 local solar time under the camera</caption>
+ * new Sun({ localDateTime: new Date(2026, 7, 3, 21, 30) })
+ *
+ * @param {ISunParams} [options] - Options:
+ * @param {number} [options.activationHeight=12079000.0] - Camera height above which the Sun takes its real position by the clock.
+ * @param {number} [options.offsetVertical=-5000000] - Vertical offset of the camera following light.
+ * @param {number} [options.offsetHorizontal=5000000] - Horizontal offset of the camera following light.
+ * @param {boolean} [options.stopped=false] - Stops the control, leaving the Sun on its real position by the clock.
+ * @param {Date} [options.localDateTime] - Lights the scene by a fixed local apparent solar time under the camera
+ * instead of the camera following light, below activationHeight. At 12:00 the Sun stands on the meridian there,
+ * while the date sets the season. Read for the wall clock numbers it shows locally, so it is not an instant in
+ * time: one parsed from an absolute timestamp reads as the machine's time zone renders it. The Clock is left
+ * untouched, and while the control is stopped this is ignored.
  */
 export declare class Sun extends Control {
     activationHeight: number;
     offsetVertical: number;
     offsetHorizontal: number;
+    /**
+     * Fixed local apparent solar time under the camera, or null for the camera following light.
+     * @public
+     * @type {Date | null}
+     */
+    localDateTime: Date | null;
     protected _currDate: number;
     protected _prevDate: number;
+    protected _redrawDate: number;
     protected _clockPtr: Clock | null;
     protected _lightOn: boolean;
     protected _stopped: boolean;
@@ -25,12 +50,43 @@ export declare class Sun extends Control {
     protected _sunlightPosition: Vec3;
     constructor(options?: ISunParams);
     oninit(): void;
+    protected _onClockTick: () => void;
     stop(): void;
     start(): void;
     onactivate(): void;
     bindClock(clock: Clock): void;
     getPosition(): Vec3;
+    /**
+     * Sets a fixed local apparent solar time under the camera.
+     * @public
+     * @param {Date | null} localDateTime - Local date and time, or null to restore the camera following light.
+     */
+    setLocalDateTime(localDateTime: Date | null): void;
     protected _setSunPosition3v(position: Vec3): void;
+    /**
+     * Returns a light position offset from the camera along its own up and right axes,
+     * so that nearby terrain is lit regardless of the real Sun direction.
+     * @protected
+     * @param {PlanetCamera} cam - Planet camera.
+     * @returns {Vec3} -
+     */
+    protected _getCameraFollowingPosition(cam: PlanetCamera): Vec3;
+    /**
+     * Returns the julian date at which localDateTime is the local apparent solar time at lon.
+     * Local mean solar time is the first guess, then the measured subsolar longitude corrects it;
+     * that point drifts -360 degrees a day, so a residual of d degrees is worth -d / 360 of a day.
+     * @protected
+     * @param {number} lon - Longitude under the camera, degrees.
+     * @returns {JulianDate} -
+     */
+    protected _getLocalDateTimeJulian(lon: number): JulianDate;
+    /**
+     * Returns the Sun position for localDateTime at the location under the camera.
+     * @protected
+     * @param {PlanetCamera} cam - Planet camera.
+     * @returns {Vec3} -
+     */
+    protected _getLocalDateTimePosition(cam: PlanetCamera): Vec3;
     protected _draw(): void;
 }
 export {};

package/lib/control/index.d.ts

@@ -3,6 +3,7 @@ export * from "./Control";
 export * from "./DebugInfo";
 export * from "./DrawingSwitcher";
 export * from "./EarthCoordinates";
+export * from "./FreeNavigation";
 export * from "./GeoImageDragControl";
 export * from "./KeyboardNavigation";
 export * from "./LayerAnimation";

package/lib/entity/EntityCollection.d.ts

@@ -241,6 +241,11 @@ declare class EntityCollection {
      * @param {boolean} visibility - Visibility flag.
      */
     setVisibility(visibility: boolean): void;
+    /**
+     * Requests the next frame to be rendered.
+     * @public
+     */
+    requestRedraw(): void;
     /**
      * Returns collection visibility.
      * @public

package/lib/entity/billboard/BaseBillboardHandler.d.ts

@@ -56,6 +56,12 @@ declare class BaseBillboardHandler {
     initProgram(): void;
     setRenderer(renderer: Renderer): void;
     refresh(): void;
+    /**
+     * Marks a buffer to be updated in the next frame and requests the frame to be rendered.
+     * @protected
+     * @param {number} index - Buffer index.
+     */
+    protected _setChangedBuffer(index: number): void;
     protected _removeBillboards(): void;
     clear(): void;
     protected _deleteBuffers(): void;

package/lib/entity/geoObject/InstanceData.d.ts

@@ -79,6 +79,12 @@ export declare class InstanceData {
     createIndicesBuffer(): void;
     createPickingColorBuffer(): void;
     refresh(): void;
+    /**
+     * Marks a buffer to be updated in the next frame and requests the frame to be rendered.
+     * @public
+     * @param {number} index - Buffer index.
+     */
+    setChangedBuffer(index: number): void;
     update(): void;
     private _createColorTexture;
     private _createNormalTexture;

package/lib/entity/geometry/GeometryHandler.d.ts

@@ -60,6 +60,7 @@ declare class GeometryHandler {
     protected _refreshPlanetNode(treeNode: Node): void;
     protected _updatePlanet(): void;
     protected refresh(): void;
+    protected _setChangedBuffer(index: number): void;
     update(): void;
     setGeometryVisibility(geometry: Geometry): void;
     setPolyColorArr(geometry: Geometry, color: Vec4): void;

package/lib/entity/label/Label.d.ts

@@ -130,7 +130,7 @@ declare class Label extends BaseBillboard {
      * @public
      * @returns {string}
      */
-    getAlign(): number;
+    getAlign(): string;
     /**
      * Sets font face family.
      * @public

package/lib/entity/pointCloud/PointCloud.d.ts

@@ -167,6 +167,7 @@ declare class PointCloud {
     insertPoint(index: number, point: Poi): void;
     draw(): void;
     drawPicking(): void;
+    protected _setChangedBuffer(index: number): void;
     /**
      * Update gl buffers.
      * @protected

package/lib/entity/pointCloud/PointCloudHandler.d.ts

@@ -30,6 +30,11 @@ declare class PointCloudHandler {
      */
     protected _pointClouds: PointCloud[];
     constructor(entityCollection: EntityCollection);
+    /**
+     * Requests the next frame to be rendered.
+     * @public
+     */
+    requestRedraw(): void;
     protected _initProgram(): void;
     bindScene(scene: Scene): void;
     add(pointCloud: PointCloud): void;

package/lib/entity/polyline/PolylineBatchRenderer.d.ts

@@ -409,6 +409,7 @@ declare class PolylineBatchRenderer {
      * @protected
      */
     protected _refresh(): void;
+    protected _setChangedBuffer(index: number): void;
     /**
      * Updates render buffers.
      * @protected

package/lib/entity/polyline/PolylineHandler.d.ts

@@ -20,6 +20,11 @@ declare class PolylineHandler {
     protected _polylines: Polyline[];
     constructor(entityCollection: EntityCollection);
     setVisibleSphere(p: Vec3, r: number): void;
+    /**
+     * Requests the next frame to be rendered.
+     * @public
+     */
+    requestRedraw(): void;
     protected _initProgram(): void;
     bindScene(scene: Scene): void;
     add(polyline: Polyline): void;

package/lib/entity/ray/RayHandler.d.ts

@@ -55,6 +55,7 @@ declare class RayHandler {
     initProgram(): void;
     setRenderer(renderer: Renderer): void;
     refresh(): void;
+    protected _setChangedBuffer(index: number): void;
     protected _removeRays(): void;
     clear(): void;
     protected _deleteBuffers(): void;

package/lib/input/KeyboardHandler.d.ts

@@ -13,6 +13,7 @@ declare class KeyboardHandler {
     protected _event: KeyboardEvent | null;
     protected _active: boolean;
     protected _stampCache: Record<string, number>;
+    onKeyEvent: ((event: KeyboardEvent) => void) | null;
     constructor();
     getcurrentlyPressedKeys(): Record<number, boolean>;
     getPressedKeysCallbacks(): Record<number, ICallbackHandler[]>;

package/lib/layer/Layer.d.ts

@@ -136,7 +136,7 @@ declare class Layer {
      */
     _planet: Planet | null;
     createTexture: Function | null;
-    nightTextureCoefficient: number;
+    protected _nightTextureCoefficient: number;
     protected _hasImageryTiles: boolean;
     /**
      * Layer global opacity.
@@ -225,6 +225,13 @@ declare class Layer {
     get instanceName(): string;
     get rendererEvents(): EventsHandler<LayerEventsList>;
     set opacity(opacity: number);
+    /**
+     * Night texture blending coefficient.
+     * @public
+     * @type {number}
+     */
+    set nightTextureCoefficient(coefficient: number);
+    get nightTextureCoefficient(): number;
     set pickingEnabled(picking: boolean);
     get pickingEnabled(): boolean;
     /**

package/lib/math/Line2.d.ts

@@ -14,7 +14,7 @@ export declare class Line2 {
      * Finds the intersection of the line with a circle.
      * @param {Vec2} center - Circle center.
      * @param {number} radius - Circle radius.
-     * @returns {[Vec2] | [Vec2, Vec2] | []}
+     * @returns {Array.<Vec2>} Zero, one, or two intersection points.
      */
     getCircleIntersection(center: Vec2, radius: number): [] | [Vec2] | [Vec2, Vec2];
 }