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 | ||
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. | |
readPixels(rect: ViewRect, selector: Pixel.Selector, receiver: Pixel.Receiver, excludeNonLocatable: booleanfalse): void | Read selected data about each pixel within a rectangular region of this Viewport. | |
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. | |
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 | |
viewsModel(modelId: string): boolean | Returns true if this Viewport is currently displaying the model with the specified Id. | |
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> | 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> | 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> | 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: 04 October, 2024