@itwin/core-frontend

/** @packageDocumentation * @module Tiles */ import { Matrix4d, Point3d, Range3d, Transform } from "@itwin/core-geometry"; import { BoundingSphere, ColorDef, ElementAlignedBox3d, Frustum, FrustumPlanes } from "@itwin/core-common"; import { IModelConnection } from "../IModelConnection"; import { GraphicBuilder } from "../render/GraphicBuilder"; import { RenderGraphic } from "../render/RenderGraphic"; import { RenderMemory } from "../render/RenderMemory"; import { RenderSystem } from "../render/RenderSystem"; import { SceneContext } from "../ViewContext"; import { Viewport } from "../Viewport"; import { LRUTileListNode, TileContent, TileDrawArgs, TileParams, TileRequest, TileRequestChannel, TileTree, TileTreeLoadStatus, TileUsageMarker, TileUser, TileUserIdSet } from "./internal"; /** @internal */ export declare function addRangeGraphic(builder: GraphicBuilder, range: Range3d, is2d: boolean): void; /** A 3d tile within a [[TileTree]]. * * A tile represents the contents of some sub-volume of the tile tree's volume. It may produce graphics representing those contents, or may have no graphics. * A tile can have child tiles that further sub-divide its own volume, providing higher-resolution representations of its contents. A tile that has no children is * referred to as a "leaf" of the tile tree. A non-leaf tile's children are produced when they are needed, and discarded when no longer needed. * A tile's contents can be discarded at any time by [[TileAdmin]] when GPU memory needs to be reclaimed; or when the Tile itself is discarded via * [[Tile.dispose]]. * * Several public [[Tile]] methods carry a warning that they should **not** be overridden by subclasses; typically a protected method exists that can be overridden instead. * For example, [[loadChildren]] should not be overridden, but it calls [[_loadChildren]], which must be overridden because it is abstract. * @public * @extensions */ export declare abstract class Tile { private _state; private _children; private _rangeGraphic?; private _rangeGraphicType; /** This tile's renderable content. */ protected _graphic?: RenderGraphic; /** True if this tile ever had graphics loaded. Used to determine when a tile's graphics were later freed to conserve memory. */ protected _hadGraphics: boolean; /** Uniquely identifies this tile's content in the context of its tree. */ protected _contentId: string; /** The current loading state of this tile's children. Child tiles are loaded on-demand, potentially asynchronously. */ protected _childrenLoadStatus: TileTreeLoadStatus; /** @internal */ protected _request?: TileRequest; /** @internal */ protected _isLeaf: boolean; /** A volume no larger than this tile's `range`, and optionally more tightly encompassing its contents, used for more accurate culling. * [[contentRange]] uses this range if defined; otherwise it uses [[range]]. */ protected _contentRange?: ElementAlignedBox3d; /** The maximum size in pixels this tile can be drawn. If the size of the tile on screen exceeds this maximum, a higher-resolution tile should be drawn in its place. */ protected _maximumSize: number; /** The [[TileTree]] to which this tile belongs. */ readonly tree: TileTree; /** The volume of space occupied by this tile. Its children are guaranteed to also be contained within this volume. */ readonly range: ElementAlignedBox3d; /** The parent of this tile, or undefined if it is the [[TileTree]]'s root tile. */ readonly parent: Tile | undefined; /** The depth of this tile within its [[TileTree]]. The root tile has a depth of zero. */ readonly depth: number; /** The bounding sphere for this tile. */ readonly boundingSphere: BoundingSphere; /** The point at the center of this tile's volume. */ get center(): Point3d; /** The radius of a sphere fully encompassing this tile's volume - used for culling. */ get radius(): number; /** Tracks the usage of this tile. After a period of disuse, the tile may be [[prune]]d to free up memory. */ readonly usageMarker: TileUsageMarker; /** Exclusively for use by LRUTileList. @internal */ previous?: LRUTileListNode; /** Exclusively for use by LRUTileList. @internal */ next?: LRUTileListNode; /** Exclusively for use by LRUTileList. @internal */ bytesUsed: number; /** Exclusively for use by LRUTileList. @internal */ tileUserIds?: TileUserIdSet; /** Load this tile's children, possibly asynchronously. Pass them to `resolve`, or an error to `reject`. */ protected abstract _loadChildren(resolve: (children: Tile[] | undefined) => void, reject: (error: Error) => void): void; /** Return the channel via which this tile's content should be requested. * @note The channel *must* be registered with `IModelApp.tileAdmin.channels`. * @see [[TileRequestChannels.getForHttp]] to create a channel that requests content over HTTP. * @see [[TileAdmin.channels]]. * @public */ abstract get channel(): TileRequestChannel; /** Return a Promise that resolves to the raw data representing this tile's content. */ abstract requestContent(isCanceled: () => boolean): Promise<TileRequest.Response>; /** Return a Promise that deserializes this tile's content from raw format produced by [[requestContent]]. */ abstract readContent(data: TileRequest.ResponseData, system: RenderSystem, isCanceled?: () => boolean): Promise<TileContent>; /** Constructor */ protected constructor(params: TileParams, tree: TileTree); /** Free memory-consuming resources owned by this tile to reduce memory pressure. * By default, this calls [[disposeContents]]. Problematic subclasses (MapTile, ImageryMapTile) may opt out for now by overriding this method to do nothing. * That option may be removed in the future. * @alpha */ freeMemory(): void; /** Dispose of resources held by this tile. */ disposeContents(): void; /** Dispose of resources held by this tile and all of its children, marking it and all of its children as "abandoned". */ [Symbol.dispose](): void; /** @deprecated in 5.0 - will not be removed until after 2026-06-13. Use [Symbol.dispose] instead. */ dispose(): void; /** This tile's child tiles, if they exist and are loaded. The children are fully contained within this tile's volume and provide higher-resolution graphics than this tile. * @see [[loadChildren]] */ get children(): Tile[] | undefined; /** The [[IModelConnection]] to which this tile belongs. */ get iModel(): IModelConnection; /** Uniquely identifies this tile's content. */ get contentId(): string; /** True if this tile's content is currently being loaded. */ get isLoading(): boolean; /** True if a request for this tile's content has been enqueued. */ get isQueued(): boolean; /** True if an attempt to load this tile's content failed. */ get isNotFound(): boolean; /** True if this tile's content has been loaded and is ready to be drawn. */ get isReady(): boolean; /** Indicates the tile should not be selected for display because it is out of the range of LODs supported by the tile provider. * @see [[ImageryMapTile.isOutOfLodRange]]. * @alpha */ get isOutOfLodRange(): boolean; /** @public */ setNotFound(): void; /** @public */ setIsReady(): void; /** @public */ setLeaf(): void; /** True if this tile has no child tiles. */ get isLeaf(): boolean; /** @internal */ get isEmpty(): boolean; /** @internal */ get isDisplayable(): boolean; /** The maximum size in pixels this tile can be drawn. If the size of the tile on screen exceeds this maximum, a higher-resolution tile should be drawn in its place. */ get maximumSize(): number; /** @internal */ get isParentDisplayable(): boolean; /** @internal */ get isUndisplayableRootTile(): boolean; /** @internal */ get request(): TileRequest | undefined; set request(request: TileRequest | undefined); /** Compute the load priority of this tile. This determines which tiles' contents are requested first. * @param _viewports The subset of `users` that are [[Viewport]]s - typically, these viewports want to display the tile's content. * @param users The [[TileUser]]s that are currently using the tile for some purpose, such as displaying its content. * @returns The priority. * @see [[TileLoadPriority]] for suggested priority values. */ computeLoadPriority(_viewports: Iterable<Viewport>, _users: Iterable<TileUser>): number; /** True if this tile has graphics ready to draw. */ get hasGraphics(): boolean; /** True if this tile has a known volume tightly encompassing its graphics. */ get hasContentRange(): boolean; /** A volume no larger than this tile's `range`, and optionally more tightly encompassing its contents, used for more accurate culling. */ get contentRange(): ElementAlignedBox3d; /** Tile contents are loaded asynchronously on demand. This member tracks the current loading status of this tile's contents. */ get loadStatus(): TileLoadStatus; /** Produce the graphics that should be drawn. */ produceGraphics(): RenderGraphic | undefined; protected setGraphic(graphic: RenderGraphic | undefined): void; /** Set this tile's content to the result of [[readContent]] */ setContent(content: TileContent): void; /** Disclose any resources owned by this tile, other than its [[RenderGraphic]]. * @internal */ protected _collectStatistics(_stats: RenderMemory.Statistics): void; /** Disclose resources owned by this tile and (by default) all of its child tiles. * @note Do not override this method! Override `_collectStatistics` instead. * @internal */ collectStatistics(stats: RenderMemory.Statistics, includeChildren?: boolean): void; /** If this tile's child tiles have not yet been requested, enqueue an asynchronous request to load them. * @note This function itself is *not* asynchronous - it immediately returns the current loading status. * @note Do not override this method - implement [[_loadChildren]]. */ protected loadChildren(): TileTreeLoadStatus; /** Dispose of this tile's child tiles and mark them as "not loaded". */ protected disposeChildren(): void; /** Returns true if this tile's bounding volume is culled by the frustum or clip volumes specified by `args`. */ protected isRegionCulled(args: TileDrawArgs): boolean; /** Returns true if this tile's content bounding volume is culled by the frustum or clip volumes specified by `args`. */ protected isContentCulled(args: TileDrawArgs): boolean; private isCulled; protected isFrustumCulled(box: Frustum, args: TileDrawArgs, testClipIntersection: boolean, sphere?: BoundingSphere): boolean; /** Determine the visibility of this tile according to the specified args. */ computeVisibility(args: TileDrawArgs): TileVisibility; /** Returns true if this tile is of at least high enough resolution to be displayed, per the supplied [[TileDrawArgs]]; or false if * a higher-resolution tile should be substituted for it. * This method is called by [[computeVisibility]] if the tile has passed all culling checks. */ protected meetsScreenSpaceError(args: TileDrawArgs): boolean; /** @internal */ extendRangeForContent(range: Range3d, matrix: Matrix4d, treeTransform: Transform, frustumPlanes?: FrustumPlanes): void; /** Primarily for debugging purposes, compute the number of tiles below this one in the [[TileTree]]. */ countDescendants(): number; /** Output this tile's graphics. */ drawGraphics(args: TileDrawArgs): void; /** @internal */ protected get rangeGraphicColor(): ColorDef; /** @internal */ getRangeGraphic(context: SceneContext): RenderGraphic | undefined; /** @internal */ protected addRangeGraphic(builder: GraphicBuilder, type: TileBoundingBoxes): void; /** Optional corners used to compute the screen size of the tile. These are used, e.g., by reality tiles with oriented bounding boxes to * produce more accurate size calculation. */ getSizeProjectionCorners(): Point3d[] | undefined; /** @internal */ clearLayers(): void; } /** Describes the current status of a [[Tile]]'s content. Tile content is loaded via an asynchronous [[TileRequest]]. * @see [[Tile.loadStatus]]. * @public * @extensions */ export declare enum TileLoadStatus { /** No attempt to load the tile's content has been made, or the tile has since been unloaded. It currently has no graphics. */ NotLoaded = 0, /** A request has been dispatched to load the tile's contents, and a response is pending. */ Queued = 1, /** A response has been received and the tile's graphics and other data are being loaded on the frontend. */ Loading = 2, /** The tile has been loaded, and if the tile is displayable it has graphics. */ Ready = 3, /** A request to load the tile's contents failed. */ NotFound = 4, /** The tile has been disposed. */ Abandoned = 5 } /** * Describes the visibility of a tile based on its size and a view frustum. * @public * @extensions */ export declare enum TileVisibility { /** The tile is entirely outside of the viewing frustum. */ OutsideFrustum = 0, /** The tile's graphics are of too low a resolution for the viewing frustum. */ TooCoarse = 1, /** The tile's graphics are of appropriate resolution for the viewing frustum. */ Visible = 2 } /** * Loosely describes the "importance" of a [[Tile]]. Requests for tiles of greater "importance" are prioritized for loading. * @note A lower priority value indicates higher importance. * @public * @extensions */ export declare enum TileLoadPriority { /** Contents of geometric models that are being interactively edited. */ Dynamic = 5, /** Background map tiles. */ Map = 15, /** Typically, tiles generated from the contents of geometric models. */ Primary = 20, /** 3d terrain tiles onto which background map imagery is draped. */ Terrain = 10, /** Typically, reality models. */ Context = 40, /** Supplementary tiles used to classify the contents of geometric or reality models. */ Classifier = 50 } /** * Options for displaying tile bounding boxes for debugging purposes. * * Bounding boxes are color-coded based on refinement strategy: * - Blue: A leaf tile (has no child tiles). * - Green: An ordinary tile (sub-divides into 4 or 8 child tiles). * - Red: A tile which refines to a single higher-resolution child occupying the same volume. * @see [[Viewport.debugBoundingBoxes]] * @public * @extensions */ export declare enum TileBoundingBoxes { /** Display no bounding boxes */ None = 0, /** Display boxes representing the tile's full volume. */ Volume = 1, /** Display boxes representing the range of the tile's contents, which may be tighter than (but never larger than) the tile's full volume. */ Content = 2, /** Display both volume and content boxes. */ Both = 3, /** Display boxes for direct children, where blue boxes indicate empty volumes. */ ChildVolumes = 4, /** Display bounding sphere. */ Sphere = 5, /** Display a transparent solid box representing the tile's full volume. * @alpha To be replaced with a separate option that applies to any of the other TileBoundingBoxes modes. */ SolidBox = 6 } //# sourceMappingURL=Tile.d.ts.map