Viewport Class
A Viewport renders the contents of one or more GeometricModels onto an HTMLCanvasElement.
It holds a ViewState object that defines its viewing parameters; the ViewState in turn defines the DisplayStyleState, CategorySelectorState, and - for SpatialViewStates - the ModelSelectorState. While a ViewState is being displayed by a Viewport, it is considered to be "attached" to that viewport; it remains attached until the Viewport is disposed of or becomes attached to a different ViewState. While the ViewState is attached to a Viewport, any changes made to the ViewState or its display style or category/model selectors will be automatically reflected in the Viewport. A ViewState can be attached to no more than one Viewport at a time.
As changes to ViewState are made, Viewports also hold a stack of previous copies of it, to allow for undo/redo (i.e. View Previous and View Next) of viewing tools.
Changes to a Viewport's state can be monitored by attaching an event listener to a variety of specific events. Most such events are triggered only once per frame, just before the Viewport's contents are rendered. For example, if the following sequence of events occurs:
- First frame is rendered
- ViewFlags are modified
- ViewFlags are modified again
- Second frame is rendered
The onDisplayStyleChanged event will be invoked exactly once, when the second frame is rendered.
@see - ScreenViewport for a viewport that can render onto the screen.
- OffScreenViewport for a viewport that can render into an off-screen buffer.
Extended by
Implements
Methods
| Name | Description | |
|---|---|---|
| addDecorations(_decorations: Decorations): void Protected | Populate a set of decoration graphics to be displayed in this viewport. | |
| addFeatureOverrideProvider(provider: FeatureOverrideProvider): boolean | Add a FeatureOverrideProvider to customize the appearance of Features within the viewport. | |
| addOnAnalysisStyleChangedListener(listener: (newStyle: AnalysisStyle) => void): () => void | Add an event listener to be invoked whenever the AnalysisStyle associated with this viewport changes. | |
| addScreenSpaceEffect(effectName: string): void | Append a screen-space effect to the list of effects applied to this Viewport. | |
| addTiledGraphicsProvider(provider: TiledGraphicsProvider): void | Register a provider of tile graphics to be drawn in this viewport. | |
| addViewedModels(models: Id64Arg): Promise<void> | Adds a set of models to the set of those currently displayed in this viewport. | |
| applyViewState(val: ViewState): void | Replace this viewport's ViewState without triggering events like onChangeView. | |
| changeBackgroundMapProps(props: BackgroundMapProps): void | See changeBackgroundMapProps | |
| changeBackgroundMapProvider(props: BackgroundMapProviderProps): void | See changeBackgroundMapProvider | |
| changeCategoryDisplay(categories: Id64Arg, display: boolean, enableAllSubCategories: booleanfalse): void | Enable or disable display of elements belonging to a set of categories specified by Id. | |
| changeModelDisplay(models: Id64Arg, display: boolean): boolean | Add or remove a set of models from those models currently displayed in this viewport. | |
| changeSubCategoryDisplay(subCategoryId: string, display: boolean): void | Change the visibility of geometry belonging to the specified subcategory when displayed in this viewport. | |
| changeView(view: ViewState, _opts?: ViewChangeOptions): void | Change the ViewState of this Viewport | |
| changeViewedModel2d(baseModelId: string, options?: ChangeViewedModel2dOptions & ViewChangeOptions & MarginOptions): Promise<void> | Attempt to change the 2d Model this Viewport is displaying, if its ViewState is a ViewState2d. | |
| changeViewedModels(modelIds: Id64Arg): boolean | Attempt to replace the set of models currently viewed by this viewport, if it is displaying a SpatialView | |
| clearAlwaysDrawn(): void | Clear the set of always-drawn elements. | |
| clearNeverDrawn(): void | Clear the set of never-drawn elements. | |
| collectStatistics(stats: RenderMemory.Statistics): void | Record graphics memory consumed by this viewport. | |
| computeViewRange(): Range3d | Compute the range of all geometry to be displayed in this viewport. | |
| createScene(context: SceneContext): void | Populate the context with the scene to be rendered by this viewport. | |
| createSceneContext(): SceneContext | Create a context appropriate for producing the scene to be rendered by this viewport, e.g., by createScene. | |
| cssPixelsToDevicePixels(cssPixels: number): number | Convert a number in CSS pixels to device pixels using this Viewport's device pixel ratio. | |
| determineVisibleDepthRange(rect?: ViewRect, result?: DepthRangeNpc): undefined | DepthRangeNpc | Computes the range of npc depth values for a region of the screen | |
| dispose(): void | Disposes of any resources owned by this object. | |
| dropFeatureOverrideProvider(provider: FeatureOverrideProvider): boolean | Removes the specified FeatureOverrideProvider from the viewport. | |
| dropModelAppearanceOverride(id: string): void | Remove any model appearance override for the specified model. | |
| dropSubCategoryOverride(id: string): void | Remove any SubCategoryOverride for the specified subcategory. | |
| dropTiledGraphicsProvider(provider: TiledGraphicsProvider): void | Remove a previously-registered provider of tile graphics. | |
| findFeatureOverrideProvider(predicate: (provider: FeatureOverrideProvider) => boolean): undefined | FeatureOverrideProvider | Locate the first registered FeatureOverrideProvider matching the supplied criterion. | |
| findFeatureOverrideProviderOfType<T>(type: Constructor<T>): undefined | T | Locate the first registered FeatureOverrideProvider of the specified class. | |
| forEachMapTreeRef(func: (ref: TileTreeReference) => void): void | Apply a function to every tile tree reference associated with the map layers displayed by this viewport. | |
| forEachTileTreeRef(func: (ref: TileTreeReference) => void): void | Apply a function to every TileTreeReference displayed by this viewport. | |
| getAuxCoordOrigin(result?: Point3d): Point3d | ||
| getAuxCoordRotation(result?: Matrix3d): Matrix3d | ||
| getContrastToBackgroundColor(): ColorDef | Get a color that will contrast to the current background color of this Viewport. | |
| getFrustum(sys: CoordSystemCoordSystem.World, adjustedBox: booleantrue, box?: Frustum): Frustum | Get an 8-point Frustum corresponding to the 8 corners of the Viewport in the specified coordinate system. | |
| getMapFeatureInfo(hit: HitDetail, options?: MapFeatureInfoOptions): Promise<MapFeatureInfo> | Obtain feature information from a map layer model, if any, identified by the specified HitDetail. | |
| getMapLayerImageryProvider(mapLayerIndex: MapLayerIndex): undefined | MapLayerImageryProvider | Return the imagery provider for the provided map-layer index. | |
| getMapLayerRange(mapLayerIndex: MapLayerIndex): Promise<undefined | MapCartoRectangle> | Returns the cartographic range of a map layer. | |
| getMapLayerScaleRangeVisibility(mapLayerIndex: MapLayerIndex): MapTileTreeScaleRangeVisibility | Return the map-layer scale range visibility for the provided map-layer index. | |
| getPixelDataNpcPoint(pixels: Pixel.Buffer, x: number, y: number, out?: Point3d): undefined | Point3d | Get the point at the specified x and y location in the pixel buffer in npc coordinates. | |
| getPixelDataWorldPoint(args: GetPixelDataWorldPointArgs): undefined | Point3d | Get the point at the specified x and y location in the pixel buffer in world coordinates. | |
| getPixelSizeAtPoint(point?: Point3d): number | Get the width of a pixel (a unit vector in the x direction in view coordinates) at a given point in world coordinates, returning the result in meters (world units). | |
| getSubCategoryAppearance(id: string): SubCategoryAppearance | Query the symbology with which geometry belonging to a specific subcategory is rendered within this viewport. | |
| getSubCategoryOverride(id: string): undefined | SubCategoryOverride | Query the symbology overrides applied to geometry belonging to a specific subcategory when rendered within this viewport. | |
| getToolTip(hit: HitDetail): Promise<string | HTMLElement> | Obtain a tooltip from the map layer or reality model, if any, identified by the specified HitDetail. | |
| getWorldFrustum(box?: Frustum): Frustum | Get a copy of the current (unadjusted) frustum of this viewport, in world coordinates. | |
| hasTiledGraphicsProvider(provider: TiledGraphicsProvider): boolean | Returns true if the specified provider has been registered with this viewport via addTiledGraphicsProvider. | |
| initialize(): void Protected | A function invoked once, after the constructor, to initialize the viewport's state. | |
| invalidateController(): void | Mark the viewport's ViewState as having changed, so that the next call to renderFrame will invoke setupFromView to synchronize with the view. | |
| invalidateDecorations(): void | Mark the current set of decorations invalid, so that they will be recreated on the next render frame. | |
| invalidateRenderPlan(): void | Mark the viewport's "render plan" as having changed, so that the next call to renderFrame will recreate it. | |
| invalidateScene(): void | Mark the viewport's scene as having changed, so that the next call to renderFrame will recreate it. | |
| invalidateSymbologyOverrides(): void | Notifies this viewport that a change in application state requires its Overrides to be recomputed. | |
| isPointVisibleXY(point: Point3d, coordSys: CoordSystemCoordSystem.World, borderPaddingFactor: number0.0): boolean | Determine whether the supplied point is visible in the viewport rectangle. | |
| isSubCategoryVisible(id: string): boolean | Determine whether geometry belonging to a specific SubCategory is visible in this viewport, assuming the containing Category is displayed. | |
| npcToView(pt: Point3d, out?: Point3d): Point3d | Convert a point from CoordSystem.Npc to CoordSystem.View | |
| npcToViewArray(pts: Point3d[]): void | Convert an array of points from CoordSystem.Npc to CoordSystem.View | |
| npcToWorld(pt: Readonly<WritableXYAndZ>, out?: Point3d): Point3d | Convert a point from CoordSystem.Npc to CoordSystem.World | |
| npcToWorldArray(pts: Point3d[]): void | Convert an array of points from CoordSystem.Npc to CoordSystem.World | |
| overrideDisplayStyle(overrides: DisplayStyleSettingsProps): void | Selectively override aspects of this viewport's display style. | |
| overrideModelAppearance(id: string, ovr: FeatureAppearance): void | Override the appearance of a model when rendered within this viewport. | |
| overrideSubCategory(id: string, ovr: SubCategoryOverride): void | Override the symbology of geometry belonging to a specific subcategory when rendered within this viewport. | |
| pixelsFromInches(inches: number): number | Converts inches to pixels based on screen DPI. | |
| queryVisibleFeatures(options: QueryVisibleFeaturesOptions, callback: QueryVisibleFeaturesCallback): void | Query which Features are currently visible within the viewport. | |
| readImage(rect: ViewRect..., targetSize: Point2d..., flipVertically: booleanfalse): undefined | ImageBuffer | Read the current image from this viewport from the rendering system. | Deprecated |
| readImageBuffer(args?: ReadImageBufferArgs): undefined | ImageBuffer | Capture the image currently rendered in this viewport, or a subset thereof. | |
| readImageToCanvas(): HTMLCanvasElement | Reads the current image from this viewport into an HTMLCanvasElement with a Canvas2dRenderingContext such that additional 2d graphics can be drawn onto it. | |
| removeScreenSpaceEffects(): void | Remove all screen-space effects from this Viewport. | |
| renderFrame(): void | Renders the contents of this viewport. | |
| replaceViewedModels(modelIds: Id64Arg): Promise<void> | Attempt to replace the set of models currently viewed by this viewport, if it is displaying a SpatialView | |
| requestRedraw(): void | Request that the Viewport redraw its contents on the next frame. | |
| resetMapLayer(mapLayerIndex: MapLayerIndex): void | Fully reset a map-layer tile tree; by calling this, the map-layer will to go through initialize process again, and all previously fetched tile will be lost. | |
| scroll(screenDist: Readonly<WritableXAndY>, options?: ViewChangeOptions): void | Scroll the view by a given number of pixels. | |
| setAlwaysDrawn(ids: Id64Set, exclusive: booleanfalse): void | Specify the Ids of a set of elements which should always be rendered within this view, regardless of category and subcategory visibility. | |
| setAnimator(animator?: Animator): void | Set or clear the animator for this Viewport. | |
| setFeatureOverrideProviderChanged(): void | Notifies this viewport that the internal state of its FeatureOverrideProvider has changed such that its | |
| setLightSettings(settings: LightSettings): void | ||
| setNeverDrawn(ids: Id64Set): void | Specify the Ids of a set of elements which should never be rendered within this view. | |
| setSolarShadowSettings(settings: SolarShadowSettings): void | ||
| setStandardRotation(id: StandardViewId): void | Orient this viewport to one of the StandardView rotations. | |
| setupFromView(pose?: ViewPose): ViewStatus | Establish the parameters of this Viewport from the current information in its ViewState | |
| setupViewFromFrustum(inFrustum: Frustum): boolean | Shortcut to call view.setupFromFrustum and then setupFromView | |
| synchWithView(_options?: ViewChangeOptions): void | Call setupFromView on this Viewport and then apply optional behavior. | |
| turnCameraOff(): void | Turn the camera off it is currently on. | |
| turnCameraOn(lensAngle?: Angle): ViewStatus | Turn the camera on if it is currently off. | |
| updateChangeFlags(newView: ViewState): void Protected | Invoked from finishUndoRedo, applyViewState, and changeView to potentially recompute change flags based on differences between current and new ViewState. | |
| view4dToWorld(input: Point4d, out?: Point3d): Point3d | Convert a point from CoordSystem.View as a Point4d to CoordSystem.View | |
| view4dToWorldArray(viewPts: Point4d[], worldPts: Point3d[]): void | Convert an array of points from CoordSystem.View as Point4ds to CoordSystem.World | |
| viewMapLayerRange(mapLayerIndex: MapLayerIndex, vp: ScreenViewport): Promise<boolean> | Changes viewport to include range of a map layer. | |
| viewsModel(modelId: string): boolean | Returns true if this Viewport is currently displaying the model with the specified Id. | |
| viewToNpc(pt: Point3d, out?: Point3d): Point3d | Convert a point from CoordSystem.View to CoordSystem.Npc | |
| viewToNpcArray(pts: Point3d[]): void | Convert an array of points from CoordSystem.View to CoordSystem.Npc | |
| viewToWorld(input: Readonly<WritableXYAndZ>, out?: Point3d): Point3d | Convert a point from CoordSystem.View to CoordSystem.World | |
| viewToWorldArray(pts: Point3d[]): void | Convert an array of points from CoordSystem.View to CoordSystem.World | |
| waitForSceneCompletion(): Promise<void> | Returns a Promise that resolves after the contents of this viewport are fully loaded and rendered. | |
| worldToNpc(pt: Readonly<WritableXYAndZ>, out?: Point3d): Point3d | Convert a point from CoordSystem.World to CoordSystem.Npc | |
| worldToNpcArray(pts: Point3d[]): void | Convert an array of points from CoordSystem.World to CoordSystem.Npc | |
| worldToView(input: Readonly<WritableXYAndZ>, out?: Point3d): Point3d | Convert a point from CoordSystem.World to CoordSystem.View | |
| worldToView4d(input: Readonly<WritableXYAndZ>, out?: Point4d): Point4d | Convert a point from CoordSystem.World to CoordSystem.View as Point4d | |
| worldToView4dArray(worldPts: Point3d[], viewPts: Point4d[]): void | Convert an array of points from CoordSystem.World to CoordSystem.View, as Point4ds | |
| worldToViewArray(pts: Point3d[]): void | Convert an array of points from CoordSystem.World to CoordSystem.View | |
| zoom(newCenter: Point3d, factor: number, options?: ViewChangeOptions & MarginOptions & OnViewExtentsError): ViewStatus | Zoom the view by a scale factor, placing the new center at the given point (world coordinates). | |
| zoomToElementProps(elementProps: ElementProps[], options?: ViewChangeOptions & MarginOptions & ZoomToOptions): void | Zoom the view to a show the tightest box around a given set of ElementProps. | |
| zoomToElements(ids: Id64Arg, options?: ViewChangeOptions & MarginOptions & ZoomToOptions): Promise<void> | Zoom the view to a show the tightest box around a given set of elements. | |
| zoomToPlacementProps(placementProps: PlacementProps[], options?: ViewChangeOptions & MarginOptions & ZoomToOptions): void | See zoomToPlacements. | |
| zoomToPlacements(placements: Placement[], options?: ViewChangeOptions & MarginOptions & ZoomToOptions): void | Zoom the view in or out to a fit to the tightest volume enclosing a given set of placements, optionally also changing the view rotation. | |
| zoomToVolume(volume: Readonly<WritableLowAndHighXYZ> | Readonly<WritableLowAndHighXY>, options?: ViewChangeOptions & MarginOptions): void | Zoom the view to a volume of space in world coordinates. |
Properties
| Name | Type | Description | |
|---|---|---|---|
| _decorationsValid Protected | boolean | If false, indicates that Decorations should be recreated when rendering the next frame. | |
| alwaysDrawn Accessor ReadOnly | undefined | Id64Set | Ids of a set of elements which should always be rendered within this view, regardless of category and subcategory visibility. | |
| analysisFraction Accessor | number | See DisplayStyleSettings.analysisFraction. | |
| antialiasSamples Accessor | number | Sets the number of MSAA samples for this viewport. | |
| areAllTileTreesLoaded Accessor ReadOnly | boolean | Returns true if all TileTrees required by this viewport have been loaded. | |
| auxCoordSystem Accessor ReadOnly | AuxCoordSystemState | ||
| backgroundMapSettings Accessor | BackgroundMapSettings | The settings controlling how a background map is displayed within a view. | |
| clipStyle Accessor | ClipStyle | See DisplayStyleSettings.clipStyle | |
| continuousRendering Accessor | boolean | Enables or disables continuous rendering. | |
| debugBoundingBoxes Accessor | TileBoundingBoxes | Determines what type (if any) of debug graphics will be displayed to visualize Tile volumes. | |
| devicePixelRatio Accessor ReadOnly | number | The device pixel ratio used by this Viewport. | |
| displayStyle Accessor | DisplayStyleState | See displayStyle | |
| emphasisSettings Accessor | Hilite.Settings | The settings that control how emphasized elements are displayed in this Viewport. | |
| featureOverrideProviders Accessor ReadOnly | Iterable<FeatureOverrideProvider, any, any> | The list of FeatureOverrideProviders registered with this viewport. | |
| flashedId Accessor | undefined | string | The Id of the currently-flashed object. | |
| flashSettings Accessor | FlashSettings | The settings that control how elements are flashed in this viewport. | |
| hilite Accessor | Hilite.Settings | The settings that control how elements are hilited in this Viewport. | |
| iModel Accessor ReadOnly | IModelConnection | The iModel of this Viewport | |
| isAlwaysDrawnExclusive Accessor ReadOnly | boolean | Returns true if the set of elements in the alwaysDrawn set are the only elements rendered within this view. | |
| isCameraOn Accessor ReadOnly | boolean | True if this is a 3d view with the camera turned on. | |
| isDisposed Accessor ReadOnly | boolean | Returns true if this Viewport's dispose method has been invoked. | |
| isFadeOutActive Accessor | boolean | Enables or disables "fade-out" mode. | |
| isGridOn Accessor ReadOnly | boolean | Determine whether the Grid display is currently enabled in this Viewport. | |
| lastFlashedElementId Accessor ReadOnly | undefined | string | The Id of the most recently flashed element, if any. | |
| lightSettings Accessor ReadOnly | undefined | LightSettings | See DisplayStyle3dSettings.lights | |
| neverDrawn Accessor ReadOnly | undefined | Id64Set | Ids of a set of elements which should not be rendered within this view. | |
| numReadyTiles Accessor ReadOnly | number | The number of tiles which were ready and met the desired level-of-detail for display in the view as of the most recently-drawn frame. | |
| numRequestedTiles Accessor ReadOnly | number | The number of outstanding requests for tiles to be displayed in this viewport. | |
| numSelectedTiles Accessor ReadOnly | number | The number of tiles selected for display in the view as of the most recently-drawn frame. | |
| onAlwaysDrawnChanged Readonly | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's set of always-drawn elements changes. | |
| onChangeView Readonly | BeEvent<(vp: Viewport, previousViewState: ViewState) => void> | Event invoked immediately when changeView is called to replace the current ViewState with a different one. | |
| onDisplayStyleChanged Readonly | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's DisplayStyleState or its members change. | |
| onDisposed Readonly | BeEvent<(vp: Viewport) => void> | Event invoked immediately when the viewport is disposed. | |
| onFeatureOverrideProviderChanged Readonly | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's FeatureOverrideProvider changes, | |
| onFeatureOverridesChanged Readonly | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's Overrides change. | |
| onFlashedIdChanged Readonly | BeEvent<(vp: Viewport, args: OnFlashedIdChangedEventArgs) => void> | Event dispatched immediately after flashedId changes, supplying the Ids of the previously and/or currently-flashed objects. | |
| onMapLayerScaleRangeVisibilityChanged Readonly | BeEvent<(layerIndexes: MapLayerScaleRangeVisibility[]) => void> | Event indicating when a map-layer scale range visibility change for the current viewport scale. | |
| onNeverDrawnChanged Readonly | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's set of never-drawn elements changes. | |
| onRender Readonly | BeEvent<(vp: Viewport) => void> | Called when the visible contents of the viewport are redrawn. | |
| onResized Readonly | BeEvent<(vp: Viewport) => void> | Event invoked after renderFrame detects that the dimensions of the viewport's ViewRect have changed. | |
| onSceneInvalidated Readonly | BeEvent<(vp: Viewport) => void> | Event invoked every time invalidateScene is called. | |
| onViewChanged Readonly | BeEvent<(vp: Viewport) => void> | Event called whenever this viewport is synchronized with its ViewState. | |
| onViewedCategoriesChanged Readonly | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's set of displayed categories changes. | |
| onViewedCategoriesPerModelChanged Readonly | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's set of Overrides changes. | |
| onViewedModelsChanged Readonly | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's set of displayed models changes. | |
| onViewportChanged Readonly | BeEvent<(vp: Viewport, changed: ChangeFlags) => void> | Event called on the next frame after any of the viewport's ChangeFlags changes. | |
| onViewUndoRedo Readonly | BeEvent<(vp: Viewport, event: ViewUndoEvent) => void> | Event called after reversing the most recent change to the Viewport from the undo stack or reapplying the | |
| perModelCategoryVisibility Accessor ReadOnly | PerModelCategoryVisibility.Overrides | Allows visibility of categories within this viewport to be overridden on a per-model basis. | |
| rotation Accessor ReadOnly | Matrix3d | This viewport's rotation matrix. | |
| screenSpaceEffects Accessor | Iterable<string, any, any> | An ordered list of names of screen-space post-processing effects to be applied to the image rendered by the Viewport. | |
| solarShadowSettings Accessor ReadOnly | undefined | SolarShadowSettings | See DisplayStyle3dSettings.solarShadows | |
| tiledGraphicsProviders Accessor ReadOnly | Iterable<TiledGraphicsProvider, any, any> | The TiledGraphicsProviders currently registered with this viewport. | |
| timePoint Accessor | undefined | number | See DisplayStyleSettings.timePoint | |
| undoDelay Static | BeDuration | Don't allow entries in the view undo buffer unless they're separated by more than this amount of time. | |
| view Accessor ReadOnly | ViewState | The ViewState for this Viewport | |
| viewDelta Accessor ReadOnly | Vector3d | The vector between the opposite corners of this viewport's extents. | |
| viewFlags Accessor | ViewFlags | Flags controlling aspects of how the contents of this viewport are rendered. | |
| viewingSpace Accessor ReadOnly | ViewingSpace | ||
| viewportId Accessor ReadOnly | number | A unique integer Id assigned to this Viewport upon construction. | |
| viewRect Accessor Abstract ReadOnly | ViewRect | Get the rectangle of this Viewport in CoordSystem.View coordinates. | |
| worldToNpcMap Accessor ReadOnly | Map4d | Provides conversions between world and Npc (non-dimensional perspective) coordinates. | |
| worldToViewMap Accessor ReadOnly | Map4d | Provides conversions between world and view coordinates. |
Defined in
Last Updated: 14 November, 2024
Found something wrong, missing, or unclear on this page?Raise an issue in our repo.