API Reference > imodeljs-frontend > Views > ScreenViewport

ScreenViewport Class

An interactive Viewport that exists within an HTMLDivElement. ScreenViewports can receive HTML events. To render the contents of a ScreenViewport, it must be added to the ViewManager via ViewManager.addViewport(). Every frame, the ViewManager will update the Viewport's state and re-render its contents if anything has changed. To halt this loop, use ViewManager.dropViewport() to remove the viewport from the ViewManager.

A ScreenViewport internally owns significant WebGL resources which must be explicitly disposed of when the viewport is no longer needed. This is achieved by invoking the viewport's dispose() method. ViewManager.dropViewport() invokes dispose() on the viewport by default.

The lifetime of a ScreenViewport typically follows a pattern:

 1. Application creates the viewport via ScreenViewport.create()
 2. The viewport is added to the render loop via ViewManager.addViewport()
 3. When the application is finished with the viewport, it removes it from the render loop and disposes of it via ViewManager.dropViewport().

In some cases it may be useful to temporarily suspend a viewport's render loop. In this case the lifetime of the viewport proceeds as follows:

 1. Application creates the viewport via ScreenViewport.create()
 2. The viewport is added to the render loop via ViewManager.addViewport()
 3. At some point the render loop is suspended via ViewManager.dropViewport(viewport, false), indicating the viewport should not be disposed.
 4. Optionally, resume rendering by returning to step 2.
 5. When the application is finished with the viewport:
   5a. If it is currently registered with the ViewManager, it is dropped and disposed of via ViewManager.dropViewport()
   5b. Otherwise, it is disposed of by invoking its dispose() method directly.

Extends

Implements

Methods

Name Description
changeView(view: ViewState, opts?: ViewChangeOptions): void Change the ViewState of this Viewport  
clearViewUndo(): void Clear the undo buffers of this Viewport.  
doRedo(animationTime?: BeDuration): void Re-applies the most recently un-done change to the Viewport from the redo stack.  
doUndo(animationTime?: BeDuration): void Reverses the most recent change to the Viewport from the undo stack.  
getClientRect(): ClientRect Get the ClientRect of the canvas for this Viewport.  
openToolTip(message: HTMLElement | string, location?: XAndY, options?: ToolTipOptions): void Open the toolTip window in this ScreenViewport with the supplied message and location.  
pickNearestVisibleGeometry(pickPoint: Point3d, radius?: number, allowNonLocatable: boolean = true, out?: Primitives.Point3d): Point3d | undefined Find a point on geometry visible in this Viewport, within a radius of supplied pick point.  
resetUndo(): void Clear the view undo buffer and establish the current ViewState as the new baseline.  
saveViewUndo(): void Saves the current state of this viewport's ViewState in the undo stack, such that it can be restored by a call to ScreenViewport.doUndo.  
setCursor(cursor: string = "default"): void Change the cursor for this Viewport  
setEventController(controller?: EventController): void Set the event controller for this Viewport.  
create(parentDiv: HTMLDivElement, view: ViewState): ScreenViewport Static Create a new ScreenViewport that shows a View of an iModel into an HTMLDivElement.  

Inherited methods

Name Inherited from Description
addViewedModels(models: Id64Arg): Promise<void> Viewport Adds a set of models to the set of those currently displayed in this viewport.
changeBackgroundMapProps(props: BackgroundMapProps): void Viewport Modify a subset of the background map display settings.
changeCategoryDisplay(categories: Id64Arg, display: boolean, enableAllSubCategories: boolean = false): void Viewport Enable or disable display of elements belonging to a set of categories specified by Id.
changeModelDisplay(models: Id64Arg, display: boolean): boolean Viewport Add or remove a set of models from those models currently displayed in this viewport.
changeViewedModel2d(baseModelId: Id64String, options?: ChangeViewedModel2dOptions & ViewChangeOptions): Promise<void> Viewport Attempt to change the 2d Model this Viewport is displaying, if its ViewState is a ViewState2d.
changeViewedModels(modelIds: Id64Arg): boolean Viewport Attempt to replace the set of models currently viewed by this viewport, if it is displaying a SpatialView
clearAlwaysDrawn(): void Viewport Clear the set of always-drawn elements.
clearNeverDrawn(): void Viewport Clear the set of never-drawn elements.
cssPixelsToDevicePixels(cssPixels: number): number Viewport Convert a number in CSS pixels to device pixels using this Viewport's device pixel ratio.
determineVisibleDepthRange(rect?: ViewRect, result?: DepthRangeNpc): DepthRangeNpc | undefined Viewport Computes the range of npc depth values for a region of the screen
dispose(): void Viewport  
dropSubCategoryOverride(id: Id64String): void Viewport Remove any SubCategoryOverride for the specified subcategory.
getAuxCoordOrigin(result?: Primitives.Point3d): Point3d Viewport  
getAuxCoordRotation(result?: Matrix3d): Matrix3d Viewport  
getContrastToBackgroundColor(): ColorDef Viewport Get a color that will contrast to the current background color of this Viewport.
getFrustum(sys: CoordSystem = CoordSystem.World, adjustedBox: boolean = true, box?: Frustum): Frustum Viewport Get an 8-point Frustum corresponding to the 8 corners of the Viewport in the specified coordinate system.
getPixelDataNpcPoint(pixels: Pixel.Buffer, x: number, y: number, out?: Primitives.Point3d): Point3d | undefined Viewport Get the point at the specified x and y location in the pixel buffer in npc coordinates
getPixelDataWorldPoint(pixels: Pixel.Buffer, x: number, y: number, out?: Primitives.Point3d): Point3d | undefined Viewport Get the point at the specified x and y location in the pixel buffer in world coordinates
getPixelSizeAtPoint(point?: Primitives.Point3d): number Viewport 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: Id64String): SubCategoryAppearance Viewport Query the symbology with which geometry belonging to a specific subcategory is rendered within this viewport.
getSubCategoryOverride(id: Id64String): SubCategoryOverride | undefined Viewport Query the symbology overrides applied to geometry belonging to a specific subcategory when rendered within this viewport.
getWorldFrustum(box?: Frustum): Frustum Viewport Get a copy of the current (unadjusted) frustum of this viewport, in world coordinates.
invalidateDecorations(): void Viewport Mark the current set of decorations invalid, so that they will be recreated on the next render frame.
isSubCategoryVisible(id: Id64String): boolean Viewport Determine whether geometry belonging to a specific SubCategory is visible in this viewport, assuming the containing Category is displayed.
npcToView(pt: Point3d, out?: Primitives.Point3d): Point3d Viewport Convert a point from CoordSystem.Npc to CoordSystem.View
npcToViewArray(pts: Point3d[]): void Viewport Convert an array of points from CoordSystem.Npc to CoordSystem.View
npcToWorld(pt: XYAndZ, out?: Primitives.Point3d): Point3d Viewport Convert a point from CoordSystem.Npc to CoordSystem.World
npcToWorldArray(pts: Point3d[]): void Viewport Convert an array of points from CoordSystem.Npc to CoordSystem.World
overrideSubCategory(id: Id64String, ovr: SubCategoryOverride): void Viewport Override the symbology of geometry belonging to a specific subcategory when rendered within this viewport.
pixelsFromInches(inches: number): number Viewport 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 Viewport Read the current image from this viewport from the rendering system.
readPixels(rect: ViewRect, selector: Pixel.Selector, receiver: Pixel.Receiver, excludeNonLocatable: boolean = false): void Viewport Read selected data about each pixel within a rectangular region of this Viewport.
replaceViewedModels(modelIds: Id64Arg): Promise<void> Viewport Attempt to replace the set of models currently viewed by this viewport, if it is displaying a SpatialView
scroll(screenDist: XAndY, options?: ViewChangeOptions): void Viewport Scroll the view by a given number of pixels.
setAlwaysDrawn(ids: Id64Set, exclusive: boolean = false): void Viewport 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 Viewport Set or clear the animator for this Viewport.
setFeatureOverrideProviderChanged(): void Viewport Notifies this viewport that the internal state of its FeatureOverrideProvider has changed such that its
setNeverDrawn(ids: Id64Set): void Viewport Specify the Ids of a set of elements which should never be rendered within this view.
setStandardRotation(id: StandardViewId): void Viewport Orient this viewport to one of the StandardView rotations.
setupFromView(pose?: ViewPose): ViewStatus Viewport Establish the parameters of this Viewport from the current information in its ViewState
setupViewFromFrustum(inFrustum: Frustum): boolean Viewport Shortcut to call view.setupFromFrustum and then Viewport.setupFromView
turnCameraOn(lensAngle?: Angle): ViewStatus Viewport Turn the camera on if it is currently off.
updateChangeFlags(newView: ViewState): void Protected Viewport Invoked from finishUndoRedo, applyViewState, and changeView to potentially recompute change flags based on differences between current and new ViewState.
view4dToWorld(input: Point4d, out?: Primitives.Point3d): Point3d Viewport Convert a point from CoordSystem.View as a Point4d to CoordSystem.View
view4dToWorldArray(viewPts: Point4d[], worldPts: Point3d[]): void Viewport Convert an array of points from CoordSystem.View as Point4ds to CoordSystem.World
viewToNpc(pt: Point3d, out?: Primitives.Point3d): Point3d Viewport Convert a point from CoordSystem.View to CoordSystem.Npc
viewToNpcArray(pts: Point3d[]): void Viewport Convert an array of points from CoordSystem.View to CoordSystem.Npc
viewToWorld(input: XYAndZ, out?: Primitives.Point3d): Point3d Viewport Convert a point from CoordSystem.View to CoordSystem.World
viewToWorldArray(pts: Point3d[]): void Viewport Convert an array of points from CoordSystem.View to CoordSystem.World
viewsModel(modelId: Id64String): boolean Viewport Returns true if this Viewport is currently displaying the model with the specified Id.
worldToNpc(pt: XYAndZ, out?: Primitives.Point3d): Point3d Viewport Convert a point from CoordSystem.World to CoordSystem.Npc
worldToNpcArray(pts: Point3d[]): void Viewport Convert an array of points from CoordSystem.World to CoordSystem.Npc
worldToView(input: XYAndZ, out?: Primitives.Point3d): Point3d Viewport Convert a point from CoordSystem.World to CoordSystem.View
worldToView4d(input: XYAndZ, out?: Point4d): Point4d Viewport Convert a point from CoordSystem.World to CoordSystem.View as Point4d
worldToView4dArray(worldPts: Point3d[], viewPts: Point4d[]): void Viewport Convert an array of points from CoordSystem.World to CoordSystem.View, as Point4ds
worldToViewArray(pts: Point3d[]): void Viewport Convert an array of points from CoordSystem.World to CoordSystem.View
zoom(newCenter: Point3d | undefined, factor: number, options?: ViewChangeOptions): void Viewport Zoom the view by a scale factor, placing the new center at the given point (world coordinates).
zoomToElementProps(elementProps: ElementProps[], options?: ViewChangeOptions & ZoomToOptions): void Viewport Zoom the view to a show the tightest box around a given set of ElementProps.
zoomToElements(ids: Id64Arg, options?: ViewChangeOptions & ZoomToOptions): Promise<void> Viewport Zoom the view to a show the tightest box around a given set of elements.
zoomToPlacementProps(placementProps: PlacementProps[], options?: ViewChangeOptions & ZoomToOptions): void Viewport Zoom the view to a show the tightest box around a given set of PlacementProps.
zoomToVolume(volume: LowAndHighXYZ | LowAndHighXY, options?: ViewChangeOptions): void Viewport Zoom the view to a volume of space in world coordinates.

Properties

Name Type Description
canvas HTMLCanvasElement The canvas to display the view contents.  
decorationDiv HTMLDivElement The HTMLDivElement used for HTML decorations.  
isRedoPossible Accessor ReadOnly boolean True if a redoable viewing operation exists on the stack  
isUndoPossible Accessor ReadOnly boolean True if an undoable viewing operation exists on the stack  
HTMLImageElement The HTMLImageElement of the iModel.js logo displayed in this ScreenViewport Beta  
maxUndoSteps number The number of entries in the view undo/redo buffer.  
parentDiv HTMLDivElement The parent HTMLDivElement of the canvas.  
toolTipDiv HTMLDivElement The HTMLDivElement used for toolTips.  
viewRect Accessor ReadOnly ViewRect The ViewRect for this ScreenViewport.  
vpDiv HTMLDivElement The div created to hold all viewport elements.  

Inherited properties

Name Type Inherited from Description
alwaysDrawn Accessor ReadOnly Id64Set | undefined Viewport Ids of a set of elements which should always be rendered within this view, regardless of category and subcategory visibility.
If the Viewport.isAlwaysDrawnExclusive flag is also set, only those elements in this set will be drawn.
auxCoordSystem Accessor ReadOnly AuxCoordSystemState Viewport  
backgroundMapSettings Accessor BackgroundMapSettings Viewport The settings controlling how a background map is displayed within a view.
continuousRendering Accessor boolean Viewport Enables or disables continuous rendering. Ideally, during each render frame a Viewport will do as little work as possible.
To make that possible, the viewport keeps track of what has changed about its internal state from one frame to the next.
For example, if the view frustum has not changed since the previous frame, it is likely that the viewport does not need to be
re-rendered at all.

In some circumstances, it is desirable to bypass the logic that limits the amount of work performed each frame. A primary example
is a viewport that has some animations applied to it, or when diagnostic information like frames-per-second is being monitored.
devicePixelRatio Accessor ReadOnly number Viewport The device pixel ratio used by this Viewport. This value is not necessarily equal to window.devicePixelRatio.
See: https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio
displayStyle Accessor DisplayStyleState Viewport The display style controller how the contents of this viewport are rendered.
emphasisSettings Accessor Settings Viewport The settings that control how emphasized elements are displayed in this Viewport. The default settings apply a thick black silhouette to the emphasized elements.
featureOverrideProvider Accessor FeatureOverrideProvider | undefined Viewport An object which can customize the appearance of Viewport.Features within a viewport.
If defined, the provider will be invoked whenever the overrides are determined to need updating.
The overrides can be explicitly marked as needing a refresh by calling Viewport.setFeatureOverrideProviderChanged. This is typically called when
the internal state of the provider changes such that the computed overrides must also change.
hilite Accessor Settings Viewport The settings that control how elements are hilited in this Viewport.
iModel Accessor ReadOnly IModelConnection Viewport The iModel of this Viewport
isAlwaysDrawnExclusive Accessor ReadOnly boolean Viewport Returns true if the set of elements in the Viewport.alwaysDrawn set are the only elements rendered within this view.
isCameraOn Accessor ReadOnly boolean Viewport True if this is a 3d view with the camera turned on.
isDisposed Accessor ReadOnly boolean Viewport Returns true if this Viewport's Viewport.dispose method has been invoked. It is an error to attempt to interact with a disposed Viewport.
Typically a ScreenViewport becomes disposed as a result of a call to ViewManager.dropViewport, often indirectly through the unmounting of a nine-zone UI's ViewportComponent when, e.g., switching front-stages.
isFadeOutActive Accessor boolean Viewport Enables or disables "fade-out" mode. When this mode is enabled, transparent graphics are rendered with a flat alpha weight,
causing them to appear de-emphasized. This is typically used in contexts in which a handful of elements are to be emphasized in the view,
while the rest of the graphics are drawn transparently.
isGridOn Accessor ReadOnly boolean Viewport Determine whether the Grid display is currently enabled in this Viewport.
neverDrawn Accessor ReadOnly Id64Set | undefined Viewport Ids of a set of elements which should not be rendered within this view.
numReadyTiles number Viewport 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 Viewport The number of outstanding requests for tiles to be displayed in this viewport.
numSelectedTiles number Viewport The number of tiles selected for display in the view as of the most recently-drawn frame.
onAlwaysDrawnChanged BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's set of always-drawn elements changes.
onChangeView BeEvent<(vp: Viewport, previousViewState: ViewState) => void> Viewport Event invoked immediately when Viewport.changeView is called to replace the current ViewState with a different one.
onDisplayStyleChanged BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's DisplayStyleState or its members change.
onFeatureOverrideProviderChanged BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's FeatureOverrideProvider changes, or the internal state of the provider changes such that the overrides needed to be recomputed.
onFeatureOverridesChanged BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's FeatureSymbology.Overrides change.
onNeverDrawnChanged BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's set of never-drawn elements changes.
onRender BeEvent<(vp: Viewport) => void> Viewport Called when the visible contents of the viewport are redrawn.
onViewChanged BeEvent<(vp: Viewport) => void> Viewport Event called whenever this viewport is synchronized with its ViewState.
onViewedCategoriesChanged BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's set of displayed categories changes.
onViewedCategoriesPerModelChanged BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's set of PerModelCategoryVisibility.Overrides changes.
onViewedModelsChanged BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's set of displayed models changes.
onViewportChanged BeEvent<(vp: Viewport, changed: ChangeFlags) => void> Viewport Event called on the next frame after any of the viewport's ChangeFlags changes.
onViewUndoRedo BeEvent<(vp: Viewport, event: ViewUndoEvent) => void> Viewport 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.
rotation Accessor ReadOnly Matrix3d Viewport This viewport's rotation matrix.
undoDelay Static BeDuration Viewport Don't allow entries in the view undo buffer unless they're separated by more than this amount of time.
view Accessor ReadOnly ViewState Viewport The ViewState for this Viewport
viewDelta Accessor ReadOnly Vector3d Viewport The vector between the opposite corners of this viewport's extents.
viewFlags Accessor ViewFlags Viewport The ViewFlags that determine how the contents of this Viewport are rendered.
worldToViewMap Accessor ReadOnly Map4d Viewport Provides conversions between world and view coordinates.

Object Literals

Name Description
animation Static Settings that may be adjusted to control the way animations of viewing operations work.

Defined in

Last Updated: 13 June, 2024