@expofp/renderer 1.5.0 → 2.0.1

package/dist/index.d.ts

@@ -48,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
@@ -56,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
@@ -64,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
@@ -72,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.
@@ -80,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.
@@ -88,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.
@@ -97,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.
@@ -106,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;
 }
 
 /**
@@ -170,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;
 }
 
@@ -390,8 +408,6 @@ export declare type RenderableDefCollection<T = RenderableDef> = T extends Rende
  * Main class for rendering the content of a {@link SceneDef}
  */
 export declare class Renderer {
-    /** Whether to log debug information */
-    readonly debugLog: boolean;
     /** {@link HTMLCanvasElement} that this renderer is rendering to */
     readonly canvas: HTMLCanvasElement;
     private ui?;
@@ -401,12 +417,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}
      */
@@ -419,6 +440,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
      */
@@ -433,34 +458,37 @@ 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.
+     */
+    get isInitialized(): boolean;
+    /**
+     * Returns true if the renderer is disposed, meaning that all WebGL resources have been released.
      */
-    updateExternalCamera(dynamicTransformMatrix: number[]): void;
+    get isDisposed(): boolean;
     /**
-     * Initialize the scene and start the rendering loop
+     * 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
-     */
-    screenToSvg(point: Vector2Like): Vector2Like;
-    /**
-     * Main rendering loop
+     * Render a single frame
      */
     render(): void;
     /**
@@ -468,13 +496,21 @@ export declare class Renderer {
      */
     stop(): void;
     /**
-     * Dispose all WebGL resources
+     * 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;
 }
 
 /**
@@ -485,8 +521,6 @@ export declare interface RendererOptions {
     canvas: HTMLCanvasElement;
     /** Optional {@link WebGLRenderingContext} to use (e.g. for Mapbox GL JS) */
     gl?: WebGLRenderingContext;
-    /** Whether to log debug information */
-    debugLog?: boolean;
     /** Optional partial {@link UI} configuration */
     ui?: Partial<UI>;
 }
@@ -595,6 +629,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. */