API Reference > imodeljs-frontend > Views > OffScreenViewport

OffScreenViewport Class

A viewport that draws to an offscreen buffer instead of to the screen. An offscreen viewport is never added to the ViewManager, therefore does not participate in the render loop. Its dimensions are specified directly instead of being derived from an HTMLCanvasElement, and its renderFrame function must be manually invoked. Offscreen viewports can be useful for, e.g., producing an image from the contents of a view (see Viewport.readImage and Viewport.readImageToCanvas) without drawing to the screen.

Extends

Methods

Name Description
setRect(rect: ViewRect): void Change the dimensions of the viewport.  
create(options: OffScreenViewportOptions): OffScreenViewport Static    

Inherited methods

Name Inherited from Description
addFeatureOverrideProvider(provider: FeatureOverrideProvider): boolean Viewport Add a FeatureOverrideProvider to customize the appearance of Viewport.Features within the viewport.
addOnAnalysisStyleChangedListener(listener: (newStyle: undefined | AnalysisStyle) => void): () => void Viewport Add an event listener to be invoked whenever the AnalysisStyle associated with this viewport changes.
addScreenSpaceEffect(effectName: string): void Viewport Append a screen-space effect to the list of effects applied to this Viewport.
addTiledGraphicsProvider(provider: TiledGraphicsProvider): void Viewport Register a provider of tile graphics to be drawn in this viewport.
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  
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.
changeSubCategoryDisplay(subCategoryId: string, display: boolean): void Viewport Change the visibility of geometry belonging to the specified subcategory when displayed in this viewport.
changeView(view: ViewState, _opts?: ViewChangeOptions): void Viewport Change the ViewState of this Viewport
changeViewedModel2d(baseModelId: string, 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.
computeViewRange(): Range3d Viewport Compute the range of all geometry to be displayed in this viewport.
createScene(context: SceneContext): void Viewport Populate the context with the scene to be rendered by this viewport.
createSceneContext(): SceneContext Viewport Create a context appropriate for producing the scene to be rendered by this viewport, e.g., by Viewport.createScene.
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): undefined | DepthRangeNpc Viewport Computes the range of npc depth values for a region of the screen
dispose(): void Viewport  
dropFeatureOverrideProvider(provider: FeatureOverrideProvider): boolean Viewport Removes the specified FeatureOverrideProvider from the viewport.
dropModelAppearanceOverride(id: string): void Viewport Remove any model appearance override for the specified model.
dropSubCategoryOverride(id: string): void Viewport Remove any SubCategoryOverride for the specified subcategory.
dropTiledGraphicsProvider(provider: TiledGraphicsProvider): void Viewport Remove a previously-registered provider of tile graphics.
findFeatureOverrideProvider(predicate: (provider: FeatureOverrideProvider) => boolean): undefined | FeatureOverrideProvider Viewport Locate the first registered FeatureOverrideProvider matching the supplied criterion.
findFeatureOverrideProviderOfType<T>(type: Constructor<T>): undefined | T Viewport Locate the first registered FeatureOverrideProvider of the specified class.
getAuxCoordOrigin(result?: 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?: Point3d): undefined | Point3d Viewport Get the point at the specified x and y location in the pixel buffer in npc coordinates.
getPixelDataWorldPoint(args: GetPixelDataWorldPointArgs): undefined | Point3d Viewport Get the point at the specified x and y location in the pixel buffer in world coordinates.
getPixelSizeAtPoint(point?: 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: string): SubCategoryAppearance Viewport Query the symbology with which geometry belonging to a specific subcategory is rendered within this viewport.
getSubCategoryOverride(id: string): undefined | SubCategoryOverride 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.
hasTiledGraphicsProvider(provider: TiledGraphicsProvider): boolean Viewport Returns true if the specified provider has been registered with this viewport via Viewport.addTiledGraphicsProvider.
invalidateDecorations(): void Viewport Mark the current set of decorations invalid, so that they will be recreated on the next render frame.
invalidateScene(): void Viewport Mark the viewport's scene as invalid, so that the next call to Viewport.renderFrame will recreate it.
isPointVisibleXY(point: Point3d, coordSys: CoordSystem = CoordSystem.World, borderPaddingFactor: number = 0.0): boolean Viewport Determine whether the supplied point is visible in the viewport rectangle.
isSubCategoryVisible(id: string): 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?: 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: Readonly<WritableXYAndZ>, out?: 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
overrideDisplayStyle(overrides: DisplayStyleSettingsProps): void Viewport Selectively override aspects of this viewport's display style.
overrideModelAppearance(id: string, ovr: FeatureAppearance): void Viewport Override the appearance of a model when rendered within this viewport.
overrideSubCategory(id: string, 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.
queryVisibleFeatures(options: QueryVisibleFeaturesOptions, callback: QueryVisibleFeaturesCallback): void Viewport Query which Features are currently visible within the viewport.
readImage(rect: ViewRect = ..., targetSize: Point2d = ..., flipVertically: boolean = false): undefined | ImageBuffer Viewport Read the current image from this viewport from the rendering system.
readImageToCanvas(): HTMLCanvasElement Viewport 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: boolean = false): void Viewport Read selected data about each pixel within a rectangular region of this Viewport.
removeScreenSpaceEffects(): void Viewport Remove all screen-space effects from this Viewport.
renderFrame(): void Viewport Renders the contents 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
requestRedraw(): void Viewport Request that the Viewport redraw its contents on the next frame.
scroll(screenDist: Readonly<WritableXAndY>, options?: ViewChangeOptions): void Viewport Scroll the view by a given number of pixels.
setAllValid(): void Viewport Strictly for tests.
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
setFlashed(id: undefined | string, _duration?: number): void Viewport Set or clear the currently flashed element.
setLightSettings(settings: LightSettings): void Viewport  
setNeverDrawn(ids: Id64Set): void Viewport Specify the Ids of a set of elements which should never be rendered within this view.
setSolarShadowSettings(settings: SolarShadowSettings): void Viewport  
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
synchWithView(_options?: boolean | ViewChangeOptions): void Viewport Call Viewport.setupFromView on this Viewport and then apply optional behavior.
turnCameraOff(): void Viewport Turn the camera off it is currently on.
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?: 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?: 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: Readonly<WritableXYAndZ>, out?: 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: string): boolean Viewport Returns true if this Viewport is currently displaying the model with the specified Id.
worldToNpc(pt: Readonly<WritableXYAndZ>, out?: 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: Readonly<WritableXYAndZ>, out?: Point3d): Point3d Viewport Convert a point from CoordSystem.World to CoordSystem.View
worldToView4d(input: Readonly<WritableXYAndZ>, 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: undefined | Point3d, factor: number, options?: ViewChangeOptions): ViewStatus 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  
zoomToPlacements(placements: Placement[], options?: ViewChangeOptions & ZoomToOptions): void Viewport 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): void Viewport Zoom the view to a volume of space in world coordinates.

Properties

Name Type Description
_isAspectRatioLocked Protected boolean    

Inherited properties

Name Type Inherited from Description
alwaysDrawn Accessor ReadOnly undefined | Id64Set 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.
analysisFraction Accessor number Viewport  
antialiasSamples Accessor number Viewport The number of antialiasing samples to be used when rendering the contents of the viewport.
Must be an integer greater than zero. A value of 1 means antialiasing is disabled. A higher number of samples correlates generally to a higher quality image but
is also more demanding on the graphics hardware.
areAllTileTreesLoaded Accessor ReadOnly boolean Viewport Returns true if all TileTrees required by this viewport have been loaded.
auxCoordSystem Accessor ReadOnly AuxCoordSystemState Viewport  
backgroundMapSettings Accessor BackgroundMapSettings Viewport The settings controlling how a background map is displayed within a view.
clipStyle Accessor ClipStyle Viewport  
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.
debugBoundingBoxes Accessor TileBoundingBoxes Viewport Determines what type (if any) of debug graphics will be displayed to visualize Tile volumes. Chiefly for debugging.
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  
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 undefined | FeatureOverrideProvider 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.
flashedId Accessor undefined | string Viewport The Id of the currently-flashed object.
The "flashed" visual effect is typically applied to the object in the viewport currently under the mouse cursor, to indicate
it is ready to be interacted with by a tool. ToolAdmin is responsible for updating it when the mouse cursor moves.
The object is usually an Element but could also be a Model or pickable decoration produced by a Decorator.
The setter ignores any string that is not a well-formed Id64String. Passing Id64.invalid to the
setter is equivalent to passing undefined - both mean "nothing is flashed".
flashSettings Accessor FlashSettings Viewport The settings that control how elements are flashed in this viewport.
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.
lastFlashedElementId Accessor ReadOnly undefined | string Viewport The Id of the most recently flashed element, if any.
lightSettings Accessor ReadOnly undefined | LightSettings Viewport  
neverDrawn Accessor ReadOnly undefined | Id64Set Viewport Ids of a set of elements which should not be rendered within this view.
numReadyTiles Accessor ReadOnly 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.
These tiles may not have been selected because some other (probably sibling) tiles were not ready for display.
This is a useful metric for determining how "complete" the view is - e.g., one indicator of progress toward view completion can be expressed as:
(numReadyTiles) / (numReadyTiles + numRequestedTiles)
numRequestedTiles Accessor ReadOnly number Viewport The number of outstanding requests for tiles to be displayed in this viewport.
numSelectedTiles Accessor ReadOnly number Viewport The number of tiles selected for display in the view as of the most recently-drawn frame.
The tiles selected may not meet the desired level-of-detail for the view, instead being temporarily drawn while
tiles of more appropriate level-of-detail are loaded asynchronously.
onAlwaysDrawnChanged Readonly BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's set of always-drawn elements changes.
onChangeView Readonly 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 Readonly BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's DisplayStyleState or its members change.
onDisposed Readonly BeEvent<(vp: Viewport) => void> Viewport Event invoked immediately when the viewport is disposed.
onFeatureOverrideProviderChanged Readonly BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's FeatureOverrideProvider changes,
onFeatureOverridesChanged Readonly BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's FeatureSymbology.Overrides change.
onFlashedIdChanged Readonly BeEvent<(vp: Viewport, args: OnFlashedIdChangedEventArgs) => void> Viewport Event dispatched immediately after Viewport.flashedId changes, supplying the Ids of the previousl-y and/or currently-flashed objects.
onNeverDrawnChanged Readonly BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's set of never-drawn elements changes.
onRender Readonly BeEvent<(vp: Viewport) => void> Viewport Called when the visible contents of the viewport are redrawn.
onResized Readonly BeEvent<(vp: Viewport) => void> Viewport Event invoked after Viewport.renderFrame detects that the dimensions of the viewport's ViewRect have changed.
onViewChanged Readonly BeEvent<(vp: Viewport) => void> Viewport Event called whenever this viewport is synchronized with its ViewState.
onViewedCategoriesChanged Readonly BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's set of displayed categories changes.
onViewedCategoriesPerModelChanged Readonly BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's set of PerModelCategoryVisibility.Overrides changes.
onViewedModelsChanged Readonly BeEvent<(vp: Viewport) => void> Viewport Event called on the next frame after this viewport's set of displayed models changes.
onViewportChanged Readonly BeEvent<(vp: Viewport, changed: ChangeFlags) => void> Viewport Event called on the next frame after any of the viewport's ChangeFlags changes.
onViewUndoRedo Readonly 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
perModelCategoryVisibility Accessor ReadOnly PerModelCategoryVisibility.Overrides Viewport Allows visibility of categories within this viewport to be overridden on a per-model basis.
rotation Accessor ReadOnly Matrix3d Viewport This viewport's rotation matrix.
screenSpaceEffects Accessor Iterable<string> Viewport An ordered list of names of screen-space post-processing effects to be applied to the image rendered by the Viewport.
The effects are applied to the image in the order in which they appear in the list. Any names not corresponding to a registered effect are ignored.
This may have no effect if the Viewport's RenderTarget does not support screen-space effects.
solarShadowSettings Accessor ReadOnly undefined | SolarShadowSettings Viewport  
tiledGraphicsProviders Accessor ReadOnly Iterable<TiledGraphicsProvider> Viewport The TiledGraphicsProviders currently registered with this viewport.
timePoint Accessor undefined | number Viewport  
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 Flags controlling aspects of how the contents of this viewport are rendered.
viewingSpace Accessor ReadOnly ViewingSpace Viewport  
viewportId Accessor ReadOnly number Viewport A unique integer Id for this viewport that can be used for comparing and sorting Viewport objects inside collections like SortedArrays.
worldToNpcMap Accessor ReadOnly Map4d Viewport Provides conversions between world and Npc (non-dimensional perspective) coordinates.
worldToViewMap Accessor ReadOnly Map4d Viewport Provides conversions between world and view coordinates.

Defined in

Last Updated: 12 June, 2024