Viewport Class
A Viewport renders the contents of one or more Models onto an HTMLCanvasElement
.
It holds a Viewport.ViewState object that defines its viewing parameters. ViewTools may modify the ViewState object. Changes to the ViewState are only reflected in a Viewport after the Viewport.synchWithView method is called.
In general, because the Viewport essentially takes control of its attached ViewState, changes to the ViewState should be made indirectly through the Viewport's own API. Doing so ensures that synchronization between the Viewport and its ViewState is reliable and automatic. For example:
- To change the set of categories or models displayed in the Viewport, use Viewport.changeCategoryDisplay and Viewport.changeModelDisplay rather than modifying the ViewState's CategorySelectorState or ModelSelectorState directly.
- To change the ViewFlags, set Viewport.viewFlags rather than modifying the ViewState's DisplayStyleState directly.
- To modify the DisplayStyleState:
const style = viewport.displayStyle.clone(); style.backgroundColor = ColorDef.red.clone(); // or any other desired modifications viewport.displayStyle = style;
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
- ScreenViewport
- OffScreenViewport
Implements
Methods
Name | Description | |
---|---|---|
addViewedModels(models: Id64Arg): Promise<void> | Adds a set of models to the set of those currently displayed in this viewport. | |
changeBackgroundMapProps(props: BackgroundMapProps): void | Modify a subset of the background map display settings. | Beta |
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. | |
changeView(view: ViewState, _opts?: ViewChangeOptions): void | Change the ViewState of this Viewport | |
changeViewedModel2d(baseModelId: Id64String, options?: undefined): 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. | Beta |
determineVisibleDepthRange(rect?: ViewRect, result?: DepthRangeNpc): DepthRangeNpc | undefined | Computes the range of npc depth values for a region of the screen | |
dispose(): void | ||
dropSubCategoryOverride(id: Id64String): void | Remove any SubCategoryOverride for the specified subcategory. | |
getAuxCoordOrigin(result?: Primitives.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 = 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. | |
getPixelDataNpcPoint(pixels: Pixel.Buffer, x: number, y: number, out?: Primitives.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?: Primitives.Point3d): Point3d | undefined | Get the point at the specified x and y location in the pixel buffer in world coordinates | Beta |
getPixelSizeAtPoint(point?: Primitives.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: 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. | Beta |
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?: Primitives.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?: Primitives.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 | |
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. | Beta |
replaceViewedModels(modelIds: Id64Arg): Promise<void> | Attempt to replace the set of models currently viewed by this viewport, if it is displaying a SpatialView | |
scroll(screenDist: XAndY, options?: ViewChangeOptions): void | Scroll the view by a given number of pixels. | |
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. | Beta |
setFeatureOverrideProviderChanged(): void | Notifies this viewport that the internal state of its Viewport.FeatureOverrideProvider has changed such that its FeatureSymbology.Overrides should be recomputed. |
|
setNeverDrawn(ids: Id64Set): void | Specify the Ids of a set of elements which should never be rendered within this view. | |
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?: Primitives.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?: Primitives.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?: Primitives.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?: Primitives.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?: Primitives.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): void | Zoom the view by a scale factor, placing the new center at the given point (world coordinates). | |
zoomToElementProps(elementProps: ElementProps[], options?: undefined): void | Zoom the view to a show the tightest box around a given set of ElementProps. | |
zoomToElements(ids: Id64Arg, options?: undefined): Promise<void> | Zoom the view to a show the tightest box around a given set of elements. | |
zoomToPlacementProps(placementProps: PlacementProps[], options?: undefined): 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. | |
auxCoordSystem Accessor ReadOnly | AuxCoordSystemState | ||
backgroundMapSettings Accessor | BackgroundMapSettings | The settings controlling how a background map is displayed within a view. | Beta |
continuousRendering Accessor | boolean | Enables or disables continuous rendering. | |
devicePixelRatio Accessor ReadOnly | number | The device pixel ratio used by this Viewport. | Beta |
displayStyle Accessor | DisplayStyleState | The display style controller how the contents of this viewport are rendered. | |
emphasisSettings Accessor | Settings | The settings that control how emphasized elements are displayed in this Viewport. | Beta |
featureOverrideProvider Accessor | FeatureOverrideProvider | undefined | Get the current FeatureOverrideProvider for this viewport if defined. | |
hilite Accessor | 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 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. | |
neverDrawn Accessor ReadOnly | Id64Set | undefined | Ids of a set of elements which should not be rendered within this view. | |
numReadyTiles | 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 | 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. | Beta |
onChangeView | BeEvent<(vp: Viewport, previousViewState: ViewState) => void> | Event invoked immediately when Viewport.changeView is called to replace the current Viewport.ViewState with a different one. | Beta |
onDisplayStyleChanged | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's DisplayStyleState or its members change. | Beta |
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. | Beta |
onFeatureOverridesChanged | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's FeatureSymbology.Overrides change. | Beta |
onNeverDrawnChanged | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's set of never-drawn elements changes. | Beta |
onRender | BeEvent<(vp: Viewport) => void> | Called when the visible contents of the viewport are redrawn. | |
onViewChanged | BeEvent<(vp: Viewport) => void> | Event called whenever this viewport is synchronized with its Viewport.ViewState. | |
onViewedCategoriesChanged | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's set of displayed categories changes. | Beta |
onViewedCategoriesPerModelChanged | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's set of PerModelCategoryVisibility.Overrides changes. | Beta |
onViewedModelsChanged | BeEvent<(vp: Viewport) => void> | Event called on the next frame after this viewport's set of displayed models changes. | Beta |
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 |
rotation Accessor ReadOnly | Matrix3d | This viewport's rotation matrix. | |
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: 08 January, 2020