@expofp/renderer 1.4.2 → 2.0.0

package/dist/index.d.ts

@@ -2,6 +2,9 @@ import { default as default_2 } from 'stats-gl';
 import { Vector2 } from 'three';
 import { Vector2Like } from 'three';
 import { Vector2Tuple } from 'three';
+import { Vector3 } from 'three';
+import { Vector3Like } from 'three';
+import { Vector3Tuple } from 'three';
 import { WebGLRenderer } from 'three';
 
 /** Camera state returned by {@link ControlsAPI.getCameraState}. */
@@ -45,7 +48,7 @@ export declare interface ControlsAPI {
      * @param immediate If true, applies the change immediately without animation
      * @returns Promise that resolves when the zoom animation completes
      */
-    zoomBy(zoom: number, immediate?: boolean): Promise<void>;
+    zoomBy: (zoom: number, immediate?: boolean) => Promise<void>;
     /**
      * Zooms the camera to fit the given rectangle.
      * @param rect Rectangle to zoom to in SVG coordinates
@@ -53,7 +56,7 @@ export declare interface ControlsAPI {
      * @param immediate If true, applies the change immediately without animation
      * @returns Promise that resolves when the zoom animation completes
      */
-    zoomTo(rect: Rect, options?: Partial<ZoomToOptions>, immediate?: boolean): Promise<void>;
+    zoomTo: (rect: Rect, options?: Partial<ZoomToOptions>, immediate?: boolean) => Promise<void>;
     /**
      * Pans the camera by the given offset in SVG space.
      * @param x X offset in SVG space
@@ -61,7 +64,7 @@ export declare interface ControlsAPI {
      * @param immediate If true, applies the change immediately without animation
      * @returns Promise that resolves when the pan animation completes
      */
-    panBy(x: number, y: number, immediate?: boolean): Promise<void>;
+    panBy: (x: number, y: number, immediate?: boolean) => Promise<void>;
     /**
      * Pans the camera to the given coordinates in SVG space.
      * @param x X coordinate in SVG space
@@ -69,7 +72,7 @@ export declare interface ControlsAPI {
      * @param immediate If true, applies the change immediately without animation
      * @returns Promise that resolves when the pan animation completes
      */
-    panTo(x: number, y: number, immediate?: boolean): Promise<void>;
+    panTo: (x: number, y: number, immediate?: boolean) => Promise<void>;
     /**
      * Rolls the camera by the given angle in degrees.
      * Note: This method won't work if {@link ControlsAPI.handlers | handlers.roll} is disabled.
@@ -77,7 +80,7 @@ export declare interface ControlsAPI {
      * @param immediate If true, applies the change immediately without animation
      * @returns Promise that resolves when the roll animation completes
      */
-    rollBy(angle: number, immediate?: boolean): Promise<void>;
+    rollBy: (angle: number, immediate?: boolean) => Promise<void>;
     /**
      * Rolls the camera to the given angle in degrees.
      * Note: This method won't work if {@link ControlsAPI.handlers | handlers.roll} is disabled.
@@ -85,7 +88,7 @@ export declare interface ControlsAPI {
      * @param immediate If true, applies the change immediately without animation
      * @returns Promise that resolves when the roll animation completes
      */
-    rollTo(angle: number, immediate?: boolean): Promise<void>;
+    rollTo: (angle: number, immediate?: boolean) => Promise<void>;
     /**
      * Pitches the camera by the given angle in degrees.
      * Positive angles increase pitch, negative angles decrease pitch.
@@ -94,7 +97,7 @@ export declare interface ControlsAPI {
      * @param immediate If true, applies the change immediately without animation
      * @returns Promise that resolves when the pitch animation completes
      */
-    pitchBy(angle: number, immediate?: boolean): Promise<void>;
+    pitchBy: (angle: number, immediate?: boolean) => Promise<void>;
     /**
      * Pitches the camera to the given angle in degrees.
      * The angle is clamped to the 0-90 degree range.
@@ -103,30 +106,30 @@ export declare interface ControlsAPI {
      * @param immediate If true, applies the change immediately without animation
      * @returns Promise that resolves when the pitch animation completes
      */
-    pitchTo(angle: number, immediate?: boolean): Promise<void>;
+    pitchTo: (angle: number, immediate?: boolean) => Promise<void>;
     /**
      * Resets the camera to the starting state.
      * @param options Configuration for which handlers to reset
      * @param immediate If true, applies the change immediately without animation
      * @returns Promise that resolves when all reset animations complete
      */
-    resetCamera(options?: Partial<ResetCameraOptions>, immediate?: boolean): Promise<void>;
+    resetCamera: (options?: Partial<ResetCameraOptions>, immediate?: boolean) => Promise<void>;
     /**
      * Configures smooth time values for camera operations.
      * @param options Partial configuration object with time values in seconds
      */
-    configure(options: Partial<ConfigureOptions>): void;
+    configure: (options: Partial<ConfigureOptions>) => void;
     /**
      * Sets the camera bounds to restrict camera movement.
      * Note: This method must be called after the viewport is initialized by `renderer.start()`.
      * @param rect Rectangle in SVG coordinates defining the camera boundary or `undefined` to remove the boundary
      */
-    setCameraBounds(rect?: Rect): void;
+    setCameraBounds: (rect?: Rect) => void;
     /**
      * Gets the current camera state.
      * @returns Camera state object with center, zoom, roll, pitch, and ptScale
      */
-    getCameraState(): CameraState;
+    getCameraState: () => CameraState;
 }
 
 /**
@@ -136,6 +139,13 @@ export declare interface ControlsAPI {
  */
 export declare function createVector2(vector2: IVector2): Vector2;
 
+/**
+ * Converts multiple vector3 representations to a {@link Vector3} instance.
+ * @param vector3 Vector3 representation as a tuple/POJO
+ * @returns Vector3 instance
+ */
+export declare function createVector3(vector3: IVector3 | IVector2): Vector3;
+
 /**
  * Mapping of engine-wide events to their payloads
  */
@@ -160,9 +170,27 @@ export declare type EventHandler<Payload> = (payload: Payload) => void;
  * Public API for interacting with the event system
  */
 export declare interface EventsAPI {
+    /**
+     * Add an event listener for a specific event
+     * @param event - The event to listen for
+     * @param handler - The handler to call when the event is emitted
+     */
     addEventListener<E extends keyof EngineEvents>(event: E, handler: EventHandler<EngineEvents[E]>): void;
+    /**
+     * Remove an event listener for a specific event
+     * @param event - The event to remove the listener for
+     * @param handler - The handler to remove
+     */
     removeEventListener<E extends keyof EngineEvents>(event: E, handler: EventHandler<EngineEvents[E]>): void;
+    /**
+     * Check if there are any listeners for a specific event
+     * @param event - The event to check
+     * @returns true if there are listeners, false otherwise
+     */
     hasListeners<E extends keyof EngineEvents>(event: E): boolean;
+    /**
+     * Clear all event listeners
+     */
     clear(): void;
 }
 
@@ -252,6 +280,8 @@ export declare function isTextLayer(layer: LayerDef): layer is TypedLayerDef<Tex
 
 export declare type IVector2 = Vector2 | Vector2Like | Vector2Tuple;
 
+export declare type IVector3 = Vector3 | Vector3Like | Vector3Tuple;
+
 /** Layer definition */
 export declare interface LayerDef extends SharedDef {
     /** Layer's name */
@@ -260,6 +290,8 @@ export declare interface LayerDef extends SharedDef {
     interactive?: boolean;
     /** Collection of layer's children. Mixing different types of children is not supported. */
     children: RenderableDefCollection;
+    /** Layer's rendering mode, 2d or 3d. Optional, 2d by default. */
+    mode?: "2d" | "3d";
 }
 
 /** Line definition */
@@ -303,14 +335,14 @@ export declare interface PitchHandlerOptions {
 /** Polygon shape instance. */
 export declare class Polygon {
     /** Array of polygon vertices. */
-    readonly vertices: Vector2[];
+    readonly vertices: Vector3[];
     /** Array of polygon indices. Each index is a triplet of vertex indices forming a triangle. */
     readonly indices: Index[];
     /**
      * @param vertices Array of polygon vertices.
      * @param indices Array of polygon indices. Each index is a triplet of vertex indices forming a triangle.
      */
-    constructor(vertices: IVector2[], indices: Index[]);
+    constructor(vertices: (IVector3 | IVector2)[], indices: Index[]);
     /**
      * Converts a {@link Rect} to a {@link Polygon}.
      * @param rect {@link Rect} instance
@@ -387,12 +419,17 @@ export declare class Renderer {
     private viewportSystem;
     private interactionsSystem;
     private controlsSystem;
+    private controlsAPI?;
+    private eventsAPI?;
+    private viewportAPI?;
     private clock;
     private renderer;
-    private viewport?;
-    private needsRedraw;
+    private visibleRectValue?;
     private memoryInfoExtension;
-    private memoryInfo;
+    private memoryInfo?;
+    private initialized;
+    private disposed;
+    private needsRedraw;
     /**
      * @param opts {@link RendererOptions}
      */
@@ -405,6 +442,10 @@ export declare class Renderer {
      * {@link EventsAPI} instance for subscribing to internal events
      */
     get events(): EventsAPI;
+    /**
+     * {@link ViewportAPI} instance for view transforms and external transforms.
+     */
+    get viewport(): ViewportAPI;
     /**
      * Optional sub-rectangle of the viewport that is used for positioning scene's viewbox
      */
@@ -419,40 +460,59 @@ export declare class Renderer {
     get context(): WebGLRenderer;
     /* Excluded from this release type: size */
     /**
-     * Sets the renderer to external mode, where parts of rendering process are not managed by the renderer (e.g. Mapbox GL JS).
-     * @param staticTransformMatrix static transform matrix to apply to the scene
+     * Returns true if the renderer is in external mode, meaning that webgl context is managed outside of the renderer
+     * (for example, when using Mapbox GL JS as a host context). In this mode renderer will not clear the canvas before
+     * rendering, and will not automatically compute scene and camera transformations. Clients are responsible for setting
+     * the matrices manually by using {@link Renderer.viewport} methods.
      */
-    setExternalTransform(staticTransformMatrix: number[]): void;
+    get isExternalMode(): boolean;
     /**
-     * Update scene matrix from dynamic transform matrix.
-     * @param dynamicTransformMatrix dynamic transform matrix (changes every frame)
+     * Returns true if the renderer is initialized, meaning that the viewport and scene have been set up.
      */
-    updateExternalCamera(dynamicTransformMatrix: number[]): void;
+    get isInitialized(): boolean;
     /**
-     * Initialize the scene and start the rendering loop
+     * Returns true if the renderer is disposed, meaning that all WebGL resources have been released.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Initializes viewport and scene with the given scene definition.
+     * Should be called once on startup. Repeated calls will produce console warnings.
      * @param sceneDef {@link SceneDef} to render
-     * @param startLoop whether to start the rendering loop
      */
-    start(sceneDef: SceneDef, startLoop?: boolean): void;
+    init(sceneDef: SceneDef): void;
+    /**
+     * Start the rendering loop
+     */
+    start(): void;
     /**
      * Update the given defs to make them reflect the current state
      * @param defs {@link RenderableDef} array to update
      */
     update(...defs: RenderableDef[]): void;
     /**
-     * Converts coordinates from canvas space to SVG space.
-     * @param point point in canvas space (relative to the canvas's top left corner), in css pixels
-     * @returns point in SVG space
+     * Render a single frame
      */
-    screenToSvg(point: Vector2Like): Vector2Like;
+    render(): void;
     /**
-     * Main rendering loop
+     * Stop the rendering loop
      */
-    render(): void;
+    stop(): void;
+    /**
+     * Dispose all WebGL resources. This calls {@link Renderer.stop} internally.
+     * WARNING: This method is final and cannot be undone. Attempting to use the renderer after calling this method
+     * will result in a console warning and no-op methods. If you need to re-initialize the renderer, create a new instance.
+     */
+    dispose(): void;
     private resizeCanvasToDisplaySize;
     private updateMemoryInfo;
     private onContextLost;
     private onContextRestored;
+    private initContext;
+    private assertNotDisposed;
+    private assertInitialized;
+    private assertNotInitialized;
+    private assertNotExternalMode;
+    private assertExternalMode;
 }
 
 /**
@@ -573,6 +633,26 @@ export declare interface UI {
     memoryInfoPanel: HTMLDivElement;
 }
 
+/** Viewport system public API. */
+export declare interface ViewportAPI {
+    /**
+     * Convert canvas coordinates (CSS pixels, relative to canvas top-left) to SVG coordinates.
+     * @param point point in canvas space (CSS pixels)
+     * @returns point in SVG coordinates or undefined if point is outside the SVG plane
+     */
+    canvasToSvg: (point: Vector2Like) => Vector2Like | undefined;
+    /**
+     * Set static part of an svg -> px transform matrix
+     * @param staticTransformMatrix static transform matrix to apply to the scene
+     */
+    setStaticTransform: (staticTransformMatrix: number[]) => void;
+    /**
+     * Set dynamic part of an svg -> px transform matrix. Should be called every frame.
+     * @param dynamicTransformMatrix dynamic transform matrix (changes every frame)
+     */
+    setDynamicTransform: (dynamicTransformMatrix: number[]) => void;
+}
+
 /** Options for the {@link ControlsAPI.zoomTo} method. */
 export declare interface ZoomToOptions {
     /** Maximum zoom factor. */