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

• ScreenViewport
• OffScreenViewport

Implements

• IDisposable
• TileUser

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

• core/frontend/src/Viewport.ts Line 291