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 Viewport.onDisplayStyleChanged event will be invoked exactly once, when the second frame is rendered.

see ViewManager

Extended by

Implements

Methods

Name Description
addFeatureOverrideProvider(provider: FeatureOverrideProvider): boolean Add a Viewport.FeatureOverrideProvider to customize the appearance of Viewport.Features within the viewport.  
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.  
attachRealityModel(props: ContextRealityModelProps): void Attach a context reality model  
changeBackgroundMapProps(props: BackgroundMapProps): void    
changeCategoryDisplay(categories: Id64Arg, display: boolean, enableAllSubCategories: boolean = false): 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: Id64String, 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: Id64String, options?: ChangeViewedModel2dOptions & ViewChangeOptions): 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.  
cssPixelsToDevicePixels(cssPixels: number): number Convert a number in CSS pixels to device pixels using this Viewport's device pixel ratio.  
detachRealityModelByIndex(index: number): void Detach a context reality model from its index.  
determineVisibleDepthRange(rect?: ViewRect, result?: DepthRangeNpc): DepthRangeNpc | undefined Computes the range of npc depth values for a region of the screen  
dispose(): void    
dropFeatureOverrideProvider(provider: FeatureOverrideProvider): boolean Removes the specified FeatureOverrideProvider from the viewport.  
dropModelAppearanceOverride(id: Id64String): void Remove any model appearance override for the specified model.  
dropRealityModelAppearanceOverride(index: number): void Drop the appearance overrides for a "contextual" reality model displayed by this viewport. Beta  
dropSubCategoryOverride(id: Id64String): 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): FeatureOverrideProvider | undefined Locate the first registered FeatureOverrideProvider matching the supplied criterion.  
findFeatureOverrideProviderOfType<T>(type: Constructor<T>): T | undefined Locate the first registered FeatureOverrideProvider of the specified class.  
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: CoordSystem.World = CoordSystem.World, adjustedBox: boolean = true, box?: Frustum): Frustum Get an 8-point Frustum corresponding to the 8 corners of the Viewport in the specified coordinate system.  
getModelAppearanceOverride(id: Id64String): FeatureAppearance | undefined Obtain the override applied to a Viewport.Model displayed in this viewport.  
getPixelDataNpcPoint(pixels: Pixel.Buffer, x: number, y: number, out?: Point3d): Point3d | undefined Get the point at the specified x and y location in the pixel buffer in npc coordinates Beta  
getPixelDataWorldPoint(pixels: Pixel.Buffer, x: number, y: number, out?: Point3d): Point3d | undefined Get the point at the specified x and y location in the pixel buffer in world coordinates Beta  
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).  
getRealityModelAppearanceOverride(index: number): FeatureAppearance | undefined Obtain the override applied to a "contextual" reality model displayed in this viewport.  
getSubCategoryAppearance(id: Id64String): SubCategoryAppearance Query the symbology with which geometry belonging to a specific subcategory is rendered within this viewport.  
getSubCategoryOverride(id: Id64String): SubCategoryOverride | undefined Query the symbology overrides applied to geometry belonging to a specific subcategory when rendered within this viewport.  
getWorldFrustum(box?: Frustum): Frustum Get a copy of the current (unadjusted) frustum of this viewport, in world coordinates.  
invalidateDecorations(): void Mark the current set of decorations invalid, so that they will be recreated on the next render frame.  
isSubCategoryVisible(id: Id64String): 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: XYAndZ, 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: Id64String, ovr: FeatureAppearance): void Override the appearance of a model when rendered within this viewport.  
overrideRealityModelAppearance(index: number, overrides: FeatureAppearance): boolean Change the appearance overrides for a "contextual" reality model displayed by this viewport. Beta  
overrideSubCategory(id: Id64String, 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.  
readImage(rect: ViewRect = new ViewRect(0, 0, -1, -1), targetSize: Point2d = Point2d.createZero(), flipVertically: boolean = false): ImageBuffer | undefined Read the current image from this viewport from the rendering system.  
readPixels(rect: ViewRect, selector: Pixel.Selector, receiver: Pixel.Receiver, excludeNonLocatable: boolean = false): void Read selected data about each pixel within a rectangular region of this Viewport.  
removeScreenSpaceEffects(): void Remove all screen-space effects from 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.  
scroll(screenDist: XAndY, options?: ViewChangeOptions): void Scroll the view by a given number of pixels.  
setAllValid(): void Strictly for tests.  
setAlwaysDrawn(ids: Id64Set, exclusive: boolean = false): 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 Viewport.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.  
setOSMBuildingDisplay(options: OsmBuildingDisplayOptions): void   Beta  
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 Viewport.setupFromView  
synchWithView(_options?: ViewChangeOptions | boolean): void Call Viewport.setupFromView on this Viewport and then apply optional behavior.  
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  
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: XYAndZ, 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  
viewsModel(modelId: Id64String): boolean Returns true if this Viewport is currently displaying the model with the specified Id.  
worldToNpc(pt: XYAndZ, 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: XYAndZ, out?: Point3d): Point3d Convert a point from CoordSystem.World to CoordSystem.View  
worldToView4d(input: XYAndZ, 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 | undefined, factor: number, options?: ViewChangeOptions): ViewStatus Zoom the view by a scale factor, placing the new center at the given point (world coordinates).  
zoomToElementProps(elementProps: ElementProps[], options?: ViewChangeOptions & ZoomToOptions): void Zoom the view to a show the tightest box around a given set of ElementProps.  
zoomToElements(ids: Id64Arg, options?: ViewChangeOptions & ZoomToOptions): Promise<void> Zoom the view to a show the tightest box around a given set of elements.  
zoomToPlacementProps(placementProps: PlacementProps[], options?: ViewChangeOptions & ZoomToOptions): void Zoom the view to a show the tightest box around a given set of PlacementProps.  
zoomToVolume(volume: LowAndHighXYZ | LowAndHighXY, options?: ViewChangeOptions): void Zoom the view to a volume of space in world coordinates.  

Properties

Name Type Description
alwaysDrawn Accessor ReadOnly Id64Set | undefined Ids of a set of elements which should always be rendered within this view, regardless of category and subcategory visibility.  
antialiasSamples Accessor number Turn on or off antialiasing in each Viewport registered with the ViewManager. Beta   
auxCoordSystem Accessor ReadOnly AuxCoordSystemState    
backgroundMapSettings Accessor BackgroundMapSettings The settings controlling how a background map is displayed within a view.  
clipStyle Accessor ClipStyle    
continuousRendering Accessor boolean Enables or disables continuous rendering.  
devicePixelRatio Accessor ReadOnly number The device pixel ratio used by this Viewport.  
displayStyle Accessor DisplayStyleState    
emphasisSettings Accessor Settings The settings that control how emphasized elements are displayed in this Viewport.  
featureOverrideProvider Accessor FeatureOverrideProvider | undefined An object which can customize the appearance of Viewport.Features within a viewport.  
hilite Accessor Settings The settings that control how elements are hilited in this Viewport.  
iModel Accessor ReadOnly IModelConnection The iModel of this Viewport  
insideClipColor Accessor ColorDef | undefined This setting controls the color override for pixels inside a clip region.  
isAlwaysDrawnExclusive Accessor ReadOnly boolean Returns true if the set of elements in the Viewport.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 Viewport.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.  
lightSettings Accessor ReadOnly LightSettings | undefined    
neverDrawn Accessor ReadOnly Id64Set | undefined 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 BeEvent<(vp: Viewport) => void> Event called on the next frame after this viewport's set of always-drawn elements changes.  
onChangeView BeEvent<(vp: Viewport, previousViewState: ViewState) => void> Event invoked immediately when Viewport.changeView is called to replace the current ViewState with a different one.  
onDisplayStyleChanged BeEvent<(vp: Viewport) => void> Event called on the next frame after this viewport's DisplayStyleState or its members change.  
onDisposed BeEvent<(vp: Viewport) => void> Event invoked immediately when the viewport is disposed.  
onFeatureOverrideProviderChanged BeEvent<(vp: Viewport) => void> Event called on the next frame after this viewport's Viewport.FeatureOverrideProvider changes, or the internal state of the provider changes such that the overrides needed to be recomputed.  
onFeatureOverridesChanged BeEvent<(vp: Viewport) => void> Event called on the next frame after this viewport's FeatureSymbology.Overrides change.  
onNeverDrawnChanged BeEvent<(vp: Viewport) => void> Event called on the next frame after this viewport's set of never-drawn elements changes.  
onRender BeEvent<(vp: Viewport) => void> Called when the visible contents of the viewport are redrawn.  
onResized BeEvent<(vp: Viewport) => void> Event invoked after Viewport.renderFrame detects that the dimensions of the viewport's ViewRect have changed. Beta   
onViewChanged BeEvent<(vp: Viewport) => void> Event called whenever this viewport is synchronized with its ViewState.  
onViewedCategoriesChanged BeEvent<(vp: Viewport) => void> Event called on the next frame after this viewport's set of displayed categories changes.  
onViewedCategoriesPerModelChanged BeEvent<(vp: Viewport) => void> Event called on the next frame after this viewport's set of PerModelCategoryVisibility.Overrides changes.  
onViewedModelsChanged BeEvent<(vp: Viewport) => void> Event called on the next frame after this viewport's set of displayed models changes.  
onViewportChanged BeEvent<(vp: Viewport, changed: ChangeFlags) => void> Event called on the next frame after any of the viewport's ChangeFlags changes. Beta   
onViewUndoRedo BeEvent<(vp: Viewport, event: ViewUndoEvent) => void> Event called after reversing the most recent change to the Viewport from the undo stack or reapplying the most recently undone change to the Viewport from the redo stack. Beta   
outsideClipColor Accessor ColorDef | undefined This setting controls the color override for pixels outside a clip region.  
perModelCategoryVisibility Accessor ReadOnly PerModelCategoryVisibility.Overrides Allows visibility of categories within this viewport to be overridden on a per-model basis. Beta   
rotation Accessor ReadOnly Matrix3d This viewport's rotation matrix.  
screenSpaceEffects Accessor Iterable<string> An ordered list of names of screen-space post-processing effects to be applied to the image rendered by the Viewport.  
solarShadowSettings Accessor ReadOnly SolarShadowSettings | undefined    
timePoint Accessor number | undefined    
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 The ViewFlags that determine how the contents of this Viewport are rendered.  
viewRect Accessor ReadOnly ViewRect Get the rectangle of this Viewport in CoordSystem.View coordinates.  
worldToViewMap Accessor ReadOnly Map4d Provides conversions between world and view coordinates.  

Defined in

Last Updated: 25 February, 2021