s2maps-gpu/dist/ui/camera/index.d.ts

S2 Maps GPU - An open source, high-performance, and GPU-accelerated map engine for rendering large-scale, interactive maps.

/** STYLE */
import Style from 'style/index.js';
import { Projector } from './projector/index.js';
/** SOURCES */
import Animator from './animator.js';
import Cache from './cache.js';
import DragPan from './dragPan.js';
import TimeCache from './timeCache.js';
/** PAINT */
import type { Painter as GLPainter } from 'gl/painter.spec.js';
import type { Painter as GPUPainter } from 'gpu/painter.spec.js';
import type { MapOptions } from '../s2mapUI.js';
import type S2Map from 's2/s2Map.js';
import type { TileInView } from './projector/index.js';
import type { Combine, TileShared as Tile } from 'source/tile.spec.js';
import type { InteractiveObject, SourceFlushMessage, TileRequest, TileWorkerMessage } from 'workers/worker.spec.js';
import type { S2CellId, VectorPoint } from 'gis-tools/index.js';
import type { StyleDefinition, TimeSeriesStyle } from 'style/style.spec.js';
/** Resize dimensions */
export interface ResizeDimensions {
    width: number;
    height: number;
}
/** A Shared painter helps with type inference. We essentially don't care which painter we are using for most calls in Camera */
export type SharedPainter = Combine<GLPainter | GPUPainter>;
/**
 * # Camera
 *
 * The camera of the map. Maintains local cache, manages the painter, projector, and handles
 * the rendering of the map.
 *
 * The Camera also handles user interactions, map states, each frame,
 * along with any animations that might be in progress.
 *
 * Any updates that are required are sent to the Style container and any data that shipped here is
 * forwarded to the Painter.
 */
export default class Camera<P extends SharedPainter = SharedPainter> {
    #private;
    readonly parent?: S2Map;
    id: string;
    _canDraw: boolean;
    _interactive: boolean;
    style: Style;
    projector: Projector;
    painter: P;
    tileCache: Cache<bigint, Tile>;
    timeCache?: TimeCache;
    tilesInView: Tile[];
    lastTileViewState: number[];
    requestQueue: Tile[];
    wasDirtyLastFrame: boolean;
    /** Denote this mapUI is running in a separate thread */
    webworker: boolean;
    canMove: boolean;
    canZoom: boolean;
    dragPan: DragPan;
    mouseMoved: boolean;
    mousePosition: VectorPoint;
    currAnimFunction?: (now: number) => void;
    resizeQueued?: ResizeDimensions;
    currFeatures: Map<number, InteractiveObject>;
    /**
     * Initialize the mapUI
     * @param options - Map options
     * @param canvas - Canvas element we are rendering to
     * @param id - Unique identifier for the mapUI
     * @param parent - Parent mapUI means this is running on the main thread so we can make direct calls to the parent
     */
    constructor(options: MapOptions, canvas: HTMLCanvasElement, id: string, parent?: S2Map);
    /**
     * Locally called but managed by parent class S2MapsUI
     * @param _deltaZ - change in zoom
     * @param _deltaX - change in x
     * @param _deltaY - change in y
     */
    onZoom(_deltaZ: number, _deltaX?: number, _deltaY?: number): void;
    /** Locally called but managed by parent class S2MapsUI */
    render(): void;
    /**
     * Given an user defined time series, build the time cache
     * @param timeSeries - the time series to build the cache for
     */
    buildTimeCache(timeSeries: TimeSeriesStyle): void;
    /**
     * Set the style for the map
     * @param style - the style to use for the painter
     * @param ignorePosition - whether to ignore the position set in the style (keep the map where it is)
     */
    _setStyle(style: string | StyleDefinition, ignorePosition: boolean): Promise<void>;
    /**
     * Update the compass position if camera changes were made internally, like an animation or functional update
     * @param bearing - The bearing angle in degrees.
     * @param pitch - The pitch angle in degrees.
     */
    _updateCompass(bearing: number, pitch: number): void;
    /**
     * Reset the tile cache for the given sources.
     * @param sourceNames - The names of the sources to reset the tile cache for.
     * @param keepCache - Whether to keep the cache or not. don't delete any tiles, request replacements for all (for s2json since it's locally cached and fast)
     * @param awaitReplace - Whether to await the replacement of tiles or not. to avoid flickering (i.e. adding/removing markers), we can wait for an update (from source+tile workers) on how the tile should look
     * @returns An array of tile requests that need to be processed to complete the reset for the tile cache for the given sources.
     */
    _resetTileCache(sourceNames: string[], keepCache: boolean, awaitReplace: boolean): TileRequest[];
    /** Resize the camera and canvas, cleaning up animations */
    _resize(): void;
    /**
     * Set the new mouse position
     * @param posX - The x-coordinate of the mouse position
     * @param posY - The y-coordinate of the mouse position
     */
    _setMousePosition(posX: number, posY: number): void;
    /**
     * Handle a navigation event
     * @param ctrl - The navigation control
     * @param lon - The longitude change if provided
     * @param lat - The latitude change if provided
     */
    _navEvent(ctrl: 'zoomIn' | 'zoomOut', lon?: number, lat?: number): void;
    /** Handle a view change */
    _onViewUpdate(): void;
    /** Handle a mouse move event that occurs on the canvas */
    _onCanvasMouseMove(): Promise<void>;
    /**
     * Animation function for a frame
     * @param animator - The animator we pull the current position from
     * @param curTime - The current time
     */
    _animate(animator: Animator, curTime: number): void;
    /** Signal to the painter that it needs to be updated */
    _updatePainter(): void;
    /**
     * Inject data into the painter
     * @param data - The data to inject
     */
    _injectData(data: TileWorkerMessage | SourceFlushMessage): void;
    /**
     * Add a time series source
     * @param sourceName - the name of the temporal source
     * @param interval - the interval position in the source
     */
    _addTimeSource(sourceName: string, interval: number): void;
    /**
     * Get a tile from the cache given an S2CellId
     * @param tileID - the id of the tile
     * @returns the tile if the cache has it
     */
    getTile(tileID: S2CellId): undefined | Tile;
    /** @returns the tiles in the current view */
    getTiles(): Tile[];
    /**
     * Given a list of S2CellIDs, create the tiles necessary to render those IDs for future requests
     * @param tileIDs - the list of S2CellIDs
     */
    createFutureTiles(tileIDs: TileInView[]): void;
    /**
     * Internal Draw handler.
     * - Get the tiles needed for the current frame
     * - If any state changes happened since last frame, update the style, painter, and projector as needed
     * - Paint the scene
     * - If there was movement/zoom change, compute the interactive elements
     * - cleanup for the next frame
     */
    _draw(): void;
}