@rings-webgpu/core 1.0.14 → 1.0.16

package/dist/types/loader/parser/tileRenderer/TilesRenderer.d.ts

@@ -1,12 +1,331 @@
-import { Object3D } from "../../../core/entities/Object3D";
+import { Tile } from './core/Tile';
+import { TileSet, TileSetChild } from './core/TileSet';
+import { LRUCache } from './utils/LRUCache';
+import { PriorityQueue } from './utils/PriorityQueue';
+import { Vector3 } from '../../../math/Vector3';
+import { Object3D } from '../../../core/entities/Object3D';
+import { BoundingBox } from '../../../core/bound/BoundingBox';
+import { Camera3D } from '../../../core/Camera3D';
+/**
+ * Plugin interface
+ */
+export interface TilesRendererPlugin {
+    name: string;
+    priority?: number;
+    init?(renderer: TilesRenderer): void;
+    dispose?(): void;
+    [key: string]: any;
+}
+/**
+ * Statistics
+ */
+export interface TilesRendererStats {
+    parsing: number;
+    downloading: number;
+    failed: number;
+    inFrustum: number;
+    used: number;
+    active: number;
+    visible: number;
+    inCacheSinceLoad: number;
+}
+/**
+ * View frustum and error calculation result interface
+ */
+export interface ViewErrorTarget {
+    inView: boolean;
+    error: number;
+    distanceFromCamera: number;
+}
+/**
+ * Memory statistics
+ */
+export interface MemoryStats {
+    totalTiles: number;
+    loadedTiles: number;
+    cachedTiles: number;
+    totalBytes: number;
+    usedBytes: number;
+    freeBytes: number;
+    cacheHitRate: number;
+}
+/**
+ * Performance statistics
+ */
+export interface PerformanceStats {
+    updateTime: number;
+    traverseTime: number;
+    markUsedTime: number;
+    markVisibleTime: number;
+    toggleTime: number;
+    queueProcessTime: number;
+}
+/**
+ * Performance configuration options
+ */
+export interface PerformanceOptions {
+    lruCacheMinSize?: number;
+    lruCacheMaxSize?: number;
+    lruCacheMinBytes?: number;
+    lruCacheMaxBytes?: number;
+    lruCacheUnloadPercent?: number;
+    downloadQueueMaxJobs?: number;
+    parseQueueMaxJobs?: number;
+    processQueueMaxJobs?: number;
+    enablePerformanceStats?: boolean;
+    enableCacheStats?: boolean;
+}
+/**
+ * Root node loaded callback parameters
+ */
+export interface RootTileLoadedCallbackParams {
+    center: Vector3;
+    radius: number;
+    boundingBox?: BoundingBox;
+    rtcOffset?: Vector3;
+}
+/**
+ * Event listener type
+ */
+type EventListener = (event: any) => void;
+/**
+ * Event type
+ */
+type EventType = 'load-tile-set' | 'tiles-load-end' | 'load-error' | 'needs-update' | 'load-content';
+/**
+ * TilesRenderer for Rings engine
+ * Contains all core algorithms and Rings-specific implementations
+ */
 export declare class TilesRenderer {
+    rootLoadingState: number;
+    rootTileSet: TileSet | null;
+    rootURL: string | null;
+    fetchOptions: RequestInit;
+    frameCount: number;
+    isLoading: boolean;
+    lruCache: LRUCache;
+    loadQueue: PriorityQueue;
+    processNodeQueue: PriorityQueue;
+    plugins: TilesRendererPlugin[];
+    protected _queuedTiles: Tile[];
+    protected _cachedSinceLoadComplete: Set<Tile>;
+    protected _processedTiles: WeakSet<Tile>;
+    protected _visibleTiles: Set<Tile>;
+    protected _usedSet: Set<Tile>;
+    protected _cacheHits: number;
+    protected _cacheMisses: number;
+    stats: TilesRendererStats;
+    errorTarget: number;
+    errorThreshold: number;
+    maxDepth: number;
+    displayActiveTiles: boolean;
+    onRootTileLoaded?: (params: RootTileLoadedCallbackParams) => void;
+    protected rtcOffset: Vector3 | null;
+    protected _root: Tile | null;
+    protected _activeTiles: Set<Tile>;
     readonly group: Object3D;
-    private _modelList;
-    private _tileSet;
-    private _rootPath;
-    constructor();
+    cameras: Camera3D[];
+    private _cameraMap;
+    private _cameraInfo;
+    private _upRotationMatrix;
+    private _ellipsoid;
+    private _bytesUsed;
+    private _eventListeners;
+    performanceStats: PerformanceStats;
+    constructor(url?: string | null);
+    /**
+     * Get root tile
+     */
+    get root(): Tile | null;
+    /**
+     * Get load progress (0-1)
+     */
+    get loadProgress(): number;
+    /**
+     * Update method (main loop)
+     */
+    update(): void;
+    /**
+     * Traverse tile tree
+     */
+    traverse(beforeCb: ((tile: Tile, parent: Tile | null, depth: number) => boolean) | null, afterCb: ((tile: Tile, parent: Tile | null, depth: number) => boolean) | null, ensureFullyProcessed?: boolean): void;
+    /**
+     * Register plugin
+     */
+    registerPlugin(plugin: TilesRendererPlugin): void;
+    /**
+     * Unregister plugin
+     */
+    unregisterPlugin(plugin: TilesRendererPlugin | string): boolean;
+    /**
+     * Get plugin by name
+     */
+    getPluginByName(name: string): TilesRendererPlugin | null;
+    /**
+     * Calculate tile view error and screen space error
+     */
+    calculateTileViewError(tile: Tile, target: ViewErrorTarget): void;
+    /**
+     * Update camera information
+     */
+    updateCameraInfo(): void;
+    private _updateCameraInfo;
+    /**
+     * Preprocess tile node
+     */
+    preprocessNode(tileData: TileSetChild, tileSetDir: string, parentTile?: Tile | null): Tile;
+    /**
+     * Ensure children are preprocessed
+     */
+    ensureChildrenArePreprocessed(tile: Tile, immediate?: boolean): void;
+    /**
+     * Record cache hit
+     */
+    private _recordCacheHit;
+    /**
+     * Record cache miss
+     */
+    private _recordCacheMiss;
+    /**
+     * Reset cache statistics
+     */
+    resetCacheStats(): void;
+    /**
+     * Request tile content
+     */
+    requestTileContents(tile: Tile): void;
+    /**
+     * Parse tile content
+     */
+    parseTileContent(tile: Tile, uri: string, url: string): Promise<void>;
+    /**
+     * Mark tile as used
+     */
+    markTileUsed(tile: Tile): void;
+    /**
+     * Set tile active state
+     */
+    setTileActive(tile: Tile, active: boolean): void;
+    /**
+     * Set tile visibility
+     */
+    setTileVisible(tile: Tile, visible: boolean): void;
+    /**
+     * Add tile to download queue
+     */
+    queueTileForDownload(tile: Tile): void;
+    /**
+     * Dispatch event
+     */
+    dispatchEvent(event: {
+        type: string;
+        [key: string]: any;
+    }): void;
+    /**
+     * Load root Tileset
+     */
+    protected _loadRootTileSet(): Promise<TileSet>;
+    /**
+     * Setup coordinate system adjustment matrix
+     */
+    private _setupUpAxisRotation;
+    /**
+     * Apply local transform matrix to Transform
+     * Each scene only applies its own local transform, automatically accumulated through parent-child relationship
+     */
+    private _applyLocalTransform;
+    /**
+     * Apply world transform matrix to Transform
+     * Since all tiles are directly mounted under group, no parent-child relationship,
+     * need to apply accumulated world transform
+     */
+    private _applyWorldTransform;
+    /**
+     * Get base path
+     */
+    protected _getBasePath(url: string): string;
+    /**
+     * Parse URL
+     */
+    private _resolveURL;
+    /**
+     * Get URL extension
+     */
+    private _getUrlExtension;
+    /**
+     * Get memory statistics
+     */
+    getMemoryStats(): MemoryStats;
+    /**
+     * Get all loaded tiles
+     */
+    getLoadedTiles(): Tile[];
+    /**
+     * Get all visible tiles
+     */
+    getVisibleTiles(): Tile[];
+    /**
+     * Get all active tiles
+     */
+    getActiveTiles(): Tile[];
+    /**
+     * Get tile tree statistics
+     */
+    getTileTreeStats(): {
+        totalTiles: number;
+        loadedTiles: number;
+        visibleTiles: number;
+        activeTiles: number;
+        maxDepth: number;
+        averageDepth: number;
+    };
+    /**
+     * Print debug information
+     */
+    printDebugInfo(): void;
+    /**
+     * Set performance configuration
+     */
+    setPerformanceOptions(options: PerformanceOptions): void;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+    /**
+     * Rings-specific: Add camera
+     */
+    setCamera(camera: Camera3D, width: number, height: number): void;
+    /**
+     * Rings-specific: Delete camera
+     */
+    deleteCamera(camera: Camera3D): void;
+    /**
+     * Rings-specific: Set camera resolution
+     */
+    setResolution(camera: Camera3D, width: number, height: number): void;
+    /**
+     * Rings-specific: Traverse all loaded models
+     */
+    forEachLoadedModel(callback: (scene: Object3D, tile: Tile) => void): void;
+    /**
+     * Rings-specific: Estimate object memory usage
+     */
+    private _estimateBytesUsed;
+    /**
+     * Rings-specific: Add event listener
+     */
+    addEventListener(type: EventType, listener: EventListener): void;
+    /**
+     * Rings-specific: Remove event listener
+     */
+    removeEventListener(type: EventType, listener: EventListener): void;
+    /**
+     * Compatibility: Load tile set (legacy API)
+     */
     loadTileSet(rootPath: string, file: string): Promise<void>;
-    private onLoadProgress;
-    private onComplete;
-    private applyTransform;
+    /**
+     * Compatibility: Get model list (legacy API)
+     */
+    get modelList(): Object3D[];
 }
+export {};

package/dist/types/loader/parser/tileRenderer/core/BoundingVolume.d.ts

@@ -0,0 +1,51 @@
+import { Vector3 } from '../../../../math/Vector3';
+import { Matrix4 } from '../../../../math/Matrix4';
+import { BoundingBox } from '../../../../core/bound/BoundingBox';
+import { BoundingSphere } from '../../../../core/bound/BoundingSphere';
+import { Frustum } from '../../../../core/bound/Frustum';
+import { BoundingVolumeData } from './TileSet';
+export type BoundingVolumeType = 'box' | 'sphere' | 'region';
+export declare class BoundingVolume {
+    private _type;
+    private _data;
+    private _box?;
+    private _sphere?;
+    private _matrix?;
+    constructor(data: BoundingVolumeData);
+    private _parseBox;
+    private _parseSphere;
+    private _parseRegion;
+    /**
+     * get the axis aligned bounding box
+     * @param target the target bounding box
+     * @param parentTransform the optional parent transform (accumulated transform)
+     */
+    getAABB(target: BoundingBox, parentTransform?: Matrix4): BoundingBox;
+    /**
+     * get the oriented bounding box (OBB)
+     */
+    getOBB(targetBox: BoundingBox, targetMatrix: Matrix4): void;
+    /**
+     * get the bounding sphere
+     */
+    getSphere(target: BoundingSphere): BoundingSphere;
+    /**
+     * get the type of the bounding volume
+     */
+    get type(): BoundingVolumeType;
+    /**
+     * calculate the distance to the point
+     */
+    /**
+     * calculate the distance to the point
+     * @param point the target point (world coordinate system)
+     * @param parentTransform the optional parent transform (accumulated transform)
+     */
+    distanceToPoint(point: Vector3, parentTransform?: Matrix4): number;
+    /**
+     * check if intersects with the frustum
+     * @param frustum the frustum (world coordinate system)
+     * @param parentTransform the optional parent transform (accumulated transform)
+     */
+    intersectsFrustum(frustum: Frustum, parentTransform?: Matrix4): boolean;
+}

package/dist/types/loader/parser/tileRenderer/core/Tile.d.ts

@@ -0,0 +1,61 @@
+import { TileSetChild, BoundingVolumeData, TileContent, TileSetChildContent } from './TileSet';
+import { Object3D } from '../../../../core/entities/Object3D';
+import { BoundingVolume } from './BoundingVolume';
+import { Matrix4 } from '../../../../math/Matrix4';
+/**
+ * tile cache data
+ */
+export interface TileCache {
+    scene?: Object3D | null;
+    boundingVolume?: BoundingVolume | null;
+    transfrom?: Matrix4;
+    worldTransform?: Matrix4;
+    transformInverse?: Matrix4;
+}
+/**
+ * runtime tile data structure
+ * based on TileSetChild, but added runtime state and cache
+ */
+export declare class Tile {
+    boundingVolume: BoundingVolumeData;
+    geometricError: number;
+    refine?: 'REPLACE' | 'ADD';
+    content?: TileContent;
+    contents?: TileSetChildContent[];
+    transform?: number[];
+    extensions?: Record<string, any>;
+    extras?: Record<string, any>;
+    parent: Tile | null;
+    children: Tile[];
+    loadingState: number;
+    used: boolean;
+    visible: boolean;
+    active: boolean;
+    inFrustum: boolean;
+    error: number;
+    distanceFromCamera: number;
+    depth: number;
+    depthFromRenderedParent: number;
+    lastFrameVisited: number;
+    isLeaf: boolean;
+    allChildrenReady: boolean;
+    hasContent: boolean;
+    hasRenderableContent: boolean;
+    hasUnrenderableContent: boolean;
+    childrenProcessed: number;
+    usedLastFrame: boolean;
+    priority?: number;
+    canTraverse: boolean;
+    canTraverseFrame: number;
+    basePath: string;
+    cached: TileCache;
+    constructor(tileData: TileSetChild, parent?: Tile | null);
+    /**
+     * add a child node
+     */
+    addChild(child: Tile): void;
+    /**
+     * reset the frame state (called at the beginning of each frame)
+     */
+    resetFrameState(frameCount: number): void;
+}

package/dist/types/loader/parser/tileRenderer/core/TileSet.d.ts

@@ -0,0 +1,91 @@
+/**
+ * bounding volume data type
+ * support three types of bounding volumes: box, sphere, region
+ */
+export type BoundingVolumeData = {
+    /** 12 numbers: center(3) + x-axis direction + half-length(3) + y-axis direction + half-length(3) + z-axis direction + half-length(3) */
+    box?: number[];
+    /** 4 numbers: center(3) + radius(1) */
+    sphere?: number[];
+    /** 6 numbers: [west, south, east, north, minHeight, maxHeight] */
+    region?: number[];
+};
+/**
+ * tile content type
+ */
+export type TileContent = {
+    uri: string;
+    extensions?: Record<string, any>;
+    extras?: Record<string, any>;
+};
+/**
+ * asset information type
+ */
+export type TileSetAsset = {
+    generatetool?: string;
+    version: string;
+    tilesetVersion?: string;
+    gltfUpAxis?: 'x' | 'y' | 'z';
+    extensions?: Record<string, any>;
+};
+/**
+ * extend TileSet class
+ */
+export declare class TileSet {
+    asset: TileSetAsset;
+    extras?: {
+        scenetree?: string;
+        [key: string]: any;
+    };
+    geometricError: number;
+    properties?: Record<string, any>;
+    refine?: 'REPLACE' | 'ADD';
+    root: TileSetRoot;
+    extensionsUsed?: string[];
+    extensionsRequired?: string[];
+    extensions?: Record<string, any>;
+}
+/**
+ * extend TileSetRoot class
+ */
+export declare class TileSetRoot {
+    boundingVolume: BoundingVolumeData;
+    children?: TileSetChild[];
+    geometricError: number;
+    transform?: number[];
+    content?: TileContent;
+    contents?: TileSetChildContent[];
+    refine?: 'REPLACE' | 'ADD';
+    extensions?: Record<string, any>;
+    extras?: Record<string, any>;
+}
+/**
+ * extend TileSetChild class
+ */
+export declare class TileSetChild {
+    boundingVolume: BoundingVolumeData;
+    geometricError: number;
+    refine?: 'REPLACE' | 'ADD';
+    content?: TileContent;
+    contents?: TileSetChildContent[];
+    children?: TileSetChild[];
+    transform?: number[];
+    extensions?: Record<string, any>;
+    extras?: Record<string, any>;
+}
+/**
+ * extend TileSetChildContent class
+ */
+export declare class TileSetChildContent {
+    uri: string;
+    group?: number;
+    metadata?: TileSetChildContentMetaData;
+}
+export declare class TileSetChildContentMetaData {
+    class?: string;
+    properties?: {
+        vertices?: number;
+        materials?: number;
+        [key: string]: any;
+    };
+}

package/dist/types/loader/parser/tileRenderer/core/constants.d.ts

@@ -0,0 +1,20 @@
+/**
+ * tile loading status constants
+ * FAILED is negative, ensure LRU cache unload failed tiles first
+ */
+export declare const FAILED = -1;
+export declare const UNLOADED = 0;
+export declare const LOADING = 1;
+export declare const PARSING = 2;
+export declare const LOADED = 3;
+/**
+ * WGS84 ellipsoid parameters (for geospatial coordinate system calculation)
+ * 参考: https://en.wikipedia.org/wiki/World_Geodetic_System
+ */
+export declare const WGS84_RADIUS = 6378137;
+export declare const WGS84_FLATTENING: number;
+export declare const WGS84_HEIGHT: number;
+/**
+ * plugin registered mark (Symbol, used to mark if the plugin is registered)
+ */
+export declare const PLUGIN_REGISTERED: unique symbol;

package/dist/types/loader/parser/tileRenderer/core/priorityCallbacks.d.ts

@@ -0,0 +1,27 @@
+import { PriorityCallback } from '../utils/PriorityQueue';
+import { UnloadPriorityCallback } from '../utils/LRUCache';
+/**
+ * download/parse queue priority callback function
+ * return 1 means a has higher priority (load first), return -1 means b has higher priority, return 0 means equal
+ *
+ * priority rules:
+ * 1. priority value smaller is higher priority
+ * 2. tiles used in current frame are higher priority
+ * 3. tiles with larger screen space error are higher priority
+ * 4. tiles closer to the camera are higher priority
+ * 5. tiles with shallower depth are higher priority
+ */
+export declare const priorityCallback: PriorityCallback;
+/**
+ * LRU cache unload priority callback function
+ * return 1 means a should be unloaded first, return -1 means b should be unloaded first, return 0 means equal
+ *
+ * unload priority rules:
+ * 1. priority value larger is higher priority
+ * 2. tiles not visited for a long time are higher priority
+ * 3. deeper nodes are higher priority (to avoid parent nodes being unloaded)
+ * 4. tiles in loading state are higher priority
+ * 5. external tilesets are unloaded last
+ * 6. tiles with smaller error are higher priority
+ */
+export declare const lruPriorityCallback: UnloadPriorityCallback;

package/dist/types/loader/parser/tileRenderer/core/traverseFunctions.d.ts

@@ -0,0 +1,20 @@
+import { Tile } from './Tile';
+import { TilesRenderer } from '../TilesRenderer';
+/**
+ * mark the tiles as used (main function)
+ */
+export declare function markUsedTiles(tile: Tile, renderer: TilesRenderer): void;
+/**
+ * mark the leaves of the "used" tree
+ */
+export declare function markUsedSetLeaves(tile: Tile, renderer: TilesRenderer): void;
+/**
+ * mark the visible tiles
+ * reference: 3DTilesRendererJS
+ */
+export declare function markVisibleTiles(tile: Tile, renderer: TilesRenderer): void;
+/**
+ * toggle the visibility of the tiles
+ * reference: 3DTilesRendererJS
+ */
+export declare function toggleTiles(tile: Tile, renderer: TilesRenderer): void;

package/dist/types/loader/parser/tileRenderer/utils/LRUCache.d.ts

@@ -0,0 +1,88 @@
+import { Tile } from '../core/Tile';
+/**
+ * LRU Cache Unload Priority Callback Function Type
+ * Return 1 means a is unloaded first, return -1 means b is unloaded first, return 0 means equal
+ */
+export type UnloadPriorityCallback = (a: Tile, b: Tile) => number;
+/**
+ * LRU Cache Item Remove Callback Function Type
+ */
+export type RemoveCallback = (item: Tile) => void;
+/**
+ * LRU Cache Implementation
+ * Used to manage tile memory, supports limits based on quantity and byte size
+ */
+export declare class LRUCache {
+    minSize: number;
+    maxSize: number;
+    minBytesSize: number;
+    maxBytesSize: number;
+    unloadPercent: number;
+    autoMarkUnused: boolean;
+    private _itemSet;
+    private _itemList;
+    private _usedSet;
+    private _callbacks;
+    private _unloadingHandle;
+    private _cachedBytes;
+    private _bytesMap;
+    private _loadedSet;
+    private _unloadPriorityCallback;
+    /**
+     * Set unload priority callback
+     */
+    set unloadPriorityCallback(cb: UnloadPriorityCallback | null);
+    get unloadPriorityCallback(): UnloadPriorityCallback | null;
+    /**
+     * Check if cache is full
+     */
+    isFull(): boolean;
+    /**
+     * Get tile memory usage
+     */
+    getMemoryUsage(item: Tile): number;
+    /**
+     * Set tile memory usage
+     */
+    setMemoryUsage(item: Tile, bytes: number): void;
+    /**
+     * Add tile to cache
+     */
+    add(item: Tile, removeCb: RemoveCallback): boolean;
+    /**
+     * Check if tile is in cache
+     */
+    has(item: Tile): boolean;
+    /**
+     * Remove tile from cache
+     */
+    remove(item: Tile): boolean;
+    /**
+     * Mark tile as used
+     */
+    markUsed(item: Tile): void;
+    /**
+     * Mark tile as unused
+     */
+    markUnused(item: Tile): void;
+    /**
+     * Schedule unload operation
+     */
+    scheduleUnload(): void;
+    /**
+     * Perform unload operation
+     */
+    private _performUnload;
+    /**
+     * Clear cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        bytes: number;
+        usedCount: number;
+    };
+}