@itwin/core-frontend 4.1.0-dev.8 → 4.1.0-dev.81

package/lib/esm/Viewport.js

@@ -33,7 +33,7 @@ import { ToolSettings } from "./tools/ToolSettings";
 import { DecorateContext, SceneContext } from "./ViewContext";
 import { viewGlobalLocation, ViewGlobalLocationConstants } from "./ViewGlobalLocation";
 import { ViewingSpace } from "./ViewingSpace";
-import { ViewRect } from "./ViewRect";
+import { ViewRect } from "./common/ViewRect";
 import { ViewStatus } from "./ViewStatus";
 import { queryVisibleFeatures } from "./render/VisibleFeature";
 import { FlashSettings } from "./FlashSettings";
@@ -92,7 +92,8 @@ export const ELEMENT_MARKED_FOR_REMOVAL = Symbol.for("@bentley/imodeljs/Viewport
  *
  * The [[Viewport.onDisplayStyleChanged]] event will be invoked exactly once, when the second frame is rendered.
  *
- * @see [[ViewManager]]
+ * @see [[ScreenViewport]] for a viewport that can render onto the screen.
+ * @see [[OffScreenViewport]] for a viewport that can render into an off-screen buffer.
  * @public
  * @extensions
  */
@@ -651,7 +652,7 @@ class Viewport {
             this.invalidateRenderPlan();
         }
     }
-    /** @internal */
+    /** Obtain a tooltip from the map layer or reality model, if any, identified by the specified [[HitDetail]]. */
     async getToolTip(hit) {
         const promises = new Array();
         if (this.displayStyle) {
@@ -666,7 +667,7 @@ class Viewport {
                 return result;
         return "";
     }
-    /** @alpha */
+    /** @beta */
     async getMapFeatureInfo(hit) {
         const promises = new Array();
         // Execute 'getMapFeatureInfo' on every tree, and make sure to handle exception for each call,
@@ -676,18 +677,23 @@ class Viewport {
         const worldPoint = hit.hitPoint.clone();
         const backgroundMapGeometry = hit.viewport.displayStyle.getBackgroundMapGeometry();
         if (undefined !== backgroundMapGeometry) {
-            featureInfo.hitPoint = await backgroundMapGeometry.dbToCartographicFromGcs(worldPoint);
+            featureInfo.hitPoint = (await backgroundMapGeometry.dbToCartographicFromGcs([worldPoint]))[0];
         }
         const results = await Promise.all(promises);
         for (const result of results)
             if (result !== undefined) {
-                if (featureInfo.layerInfo === undefined) {
-                    featureInfo.layerInfo = [];
+                if (featureInfo.layerInfos === undefined) {
+                    featureInfo.layerInfos = [];
                 }
-                featureInfo.layerInfo.push(...result);
+                featureInfo.layerInfos.push(...result);
             }
         return featureInfo;
     }
+    /** A function invoked once, after the constructor, to initialize the viewport's state.
+     * Subclasses can use this perform additional initialization, as the viewport's constructor is not directly invokable.
+     */
+    initialize() {
+    }
     /** @internal */
     constructor(target) {
         /** Event called whenever this viewport is synchronized with its [[ViewState]].
@@ -748,7 +754,9 @@ class Viewport {
         this._doContinuousRendering = false;
         /** @internal */
         this._inViewChangedEvent = false;
-        /** @internal */
+        /** If false, indicates that [[Decorations]] should be recreated when rendering the next frame.
+         * @note prefer to invoke [[invalidateDecorations]] rather than directly assigning to this property.
+         */
         this._decorationsValid = false;
         /** @internal */
         this._sceneValid = false;
@@ -1137,7 +1145,10 @@ class Viewport {
         this._changeFlags.setFeatureOverrideProvider();
         this.maybeInvalidateScene();
     }
-    /** @internal */
+    /** Notifies this viewport that a change in application state requires its [[FeatureSymbology.Overrides]] to be recomputed.
+     * @note The viewport monitors various events to automatically detect when the overrides should be recomputed. This method
+     * is only needed for changes that are not observable by the viewport itself.
+     */
     invalidateSymbologyOverrides() {
         this.setFeatureOverrideProviderChanged();
     }
@@ -1157,7 +1168,7 @@ class Viewport {
         for (const provider of this._tiledGraphicsProviders)
             provider.forEachTileTreeRef(this, (ref) => func(ref));
     }
-    /** @internal */
+    /** Apply a function to every tile tree reference associated with the map layers displayed by this viewport. */
     forEachMapTreeRef(func) {
         if (this._mapTiledGraphicsProvider)
             this._mapTiledGraphicsProvider.forEachTileTreeRef(this, (ref) => func(ref));
@@ -1209,11 +1220,11 @@ class Viewport {
     }
     /** @internal */
     mapLayerFromHit(hit) {
-        return undefined === hit.modelId ? undefined : this.mapLayerFromIds(hit.modelId, hit.sourceId);
+        return undefined === hit.modelId ? [] : this.mapLayerFromIds(hit.modelId, hit.sourceId);
     }
     /** @internal */
     mapLayerFromIds(mapTreeId, layerTreeId) {
-        return this._mapTiledGraphicsProvider?.mapLayerFromIds(mapTreeId, layerTreeId);
+        return this._mapTiledGraphicsProvider === undefined ? [] : this._mapTiledGraphicsProvider.mapLayerFromIds(mapTreeId, layerTreeId);
     }
     /** @internal */
     getTerrainHeightRange() {
@@ -2023,7 +2034,9 @@ class Viewport {
         if (requestNextAnimation || undefined !== this._animator || this.continuousRendering)
             IModelApp.requestNextAnimation();
     }
-    /** @internal */
+    /** Populate a set of decoration graphics to be displayed in this viewport.
+     * This base implementation produces no graphics.
+     */
     addDecorations(_decorations) { }
     /** Read selected data about each pixel within a rectangular region of this Viewport.
      * @param rect The area of the viewport's contents to read. The origin specifies the upper-left corner. Must lie entirely within the viewport's dimensions. This input viewport is specified using CSS pixels not device pixels.
@@ -2045,7 +2058,7 @@ class Viewport {
             return false;
         if (pixel.modelId === pixel.elementId)
             return false; // Reality Models not selectable
-        return undefined === this.mapLayerFromIds(pixel.modelId, pixel.elementId); // Maps no selectable.
+        return (0 === this.mapLayerFromIds(pixel.modelId, pixel.elementId).length); // Maps no selectable.
     }
     /** Read the current image from this viewport from the rendering system. If a "null" rectangle is supplied (@see [[ViewRect.isNull]]), the entire view is captured.
      * @param rect The area of the view to read. The origin of a viewRect must specify the upper left corner.
@@ -2156,7 +2169,11 @@ class Viewport {
                 const pixel = pixels.getPixel(x, y);
                 const modelId = pixel.modelId;
                 if (undefined !== modelId) {
-                    const transform = this.view.computeDisplayTransform({ modelId, elementId: pixel.feature?.elementId });
+                    const transform = this.view.computeDisplayTransform({
+                        modelId,
+                        elementId: pixel.feature?.elementId,
+                        viewAttachmentId: pixel.viewAttachmentId,
+                    });
                     transform?.multiplyInversePoint3d(npc, npc);
                 }
             }
@@ -2290,6 +2307,9 @@ class Viewport {
     onRequestStateChanged() {
         this.invalidateScene();
     }
+    /** @internal See [[OffScreenViewport.drawingToSheetTransform */
+    get drawingToSheetTransform() { return undefined; }
+    set drawingToSheetTransform(_) { assert(false, "drawingToSheetTransform is only relevant for OffScreenViewport"); }
 }
 /** Don't allow entries in the view undo buffer unless they're separated by more than this amount of time. */
 Viewport.undoDelay = BeDuration.fromSeconds(.5);
@@ -2319,6 +2339,8 @@ export { 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.
  * ```
+ *
+ * @see [[ScreenViewport.create]] to create a ScreenViewport.
  * @public
  * @extensions
  */
@@ -2336,6 +2358,7 @@ class ScreenViewport extends Viewport {
             throw new Error("viewport cannot be created from a div with zero width or height");
         const canvas = document.createElement("canvas");
         const vp = new this(canvas, parentDiv, IModelApp.renderSystem.createTarget(canvas));
+        vp.initialize();
         vp.changeView(view);
         return vp;
     }
@@ -2392,7 +2415,12 @@ class ScreenViewport extends Viewport {
         element.style.zIndex = zIndex.toString();
         parent.appendChild(element);
     }
-    /** @internal */
+    /** Add a new `HTMLDivElement` as a child of this viewport's div.
+     * @param className The CSS class name to apply to the div.
+     * @param overflowHidden Whether to set `div.style.overflow` to "hidden" instead of "visible".
+     * @param z The Z index of the div relative to its sibling `HTMLElement`s.
+     * @returns the new div.
+     */
     addNewDiv(className, overflowHidden, z) {
         const div = document.createElement("div");
         div.className = className;
@@ -2621,12 +2649,14 @@ class ScreenViewport extends Viewport {
     pickCanvasDecoration(pt) { return this.target.pickOverlayDecoration(pt); }
     /** Get the DOMRect of the canvas for this Viewport. */
     getClientRect() { return this.canvas.getBoundingClientRect(); }
-    /** The ViewRect for this ScreenViewport. Left and top will be 0, right will be the width, and bottom will be the height. */
+    /** The ViewRect for this ScreenViewport. Left and top will be 0, right will be the width, and bottom will be the height.
+     * @note Do not modify the ViewRect's properties.
+     */
     get viewRect() {
         this._viewRange.init(0, 0, this.canvas.clientWidth, this.canvas.clientHeight);
         return this._viewRange;
     }
-    /** @internal */
+    /** Populate a set of decoration graphics to be displayed in this viewport. */
     addDecorations(decorations) {
         // SEE: decorationDiv doc comment
         // eslint-disable-next-line deprecation/deprecation
@@ -2685,7 +2715,9 @@ class ScreenViewport extends Viewport {
         if (doAnimate)
             this.animateFrustumChange(opts);
     }
-    /** @internal */
+    /** A point in world coordinates describing an appropriate default point for a [[ViewTool]] when no more specific point is provided by the user.
+     * This point is generally managed and used by [[ViewManip]].
+     */
     get viewCmdTargetCenter() { return this._viewCmdTargetCenter; }
     set viewCmdTargetCenter(center) { this._viewCmdTargetCenter = center ? center.clone() : undefined; }
     /** True if an undoable viewing operation exists on the stack */
@@ -2848,7 +2880,7 @@ class ScreenViewport extends Viewport {
         }
         this.invalidateRenderPlan();
     }
-    /** @internal override */
+    /** Overrides [[Viewport.waitForSceneCompletion]] to allow the render loop to load graphics until the scene is complete. */
     async waitForSceneCompletion() {
         if (!IModelApp.viewManager.hasViewport(this))
             return super.waitForSceneCompletion();
@@ -2943,15 +2975,23 @@ function _clear2dCanvas(canvas) {
  * 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.readImageBuffer]] and [[Viewport.readImageToCanvas]])
  * without drawing to the screen.
+ * @see [[OffScreenViewport.create]] to create an off-screen viewport.
  * @public
  * @extensions
  */
 export class OffScreenViewport extends Viewport {
-    constructor() {
-        super(...arguments);
+    /** @internal */
+    constructor(target) {
+        super(target);
         this._isAspectRatioLocked = false;
     }
-    /** @internal see AttachToViewportArgs.drawingToSheetTransform. */
+    /** A bit of a hack to work around our ill-advised decision to always expect a RenderClipVolume to be defined in world coordinates.
+     * When we attach a section drawing to a sheet view, and the section drawing has a spatial view attached to *it*, the spatial view's clip
+     * is transformed into drawing space - but when we display it we need to transform it into world (sheet) coordinates.
+     * Fixing the actual problem (clips should always be defined in the coordinate space of the graphic branch containing them) would be quite error-prone
+     * and likely to break existing code -- so instead the SheetViewState specifies this transform to be consumed by DrawingViewState.attachToViewport.
+     * @internal
+     */
     get drawingToSheetTransform() {
         return this._drawingToSheetTransform;
     }
@@ -2969,13 +3009,16 @@ export class OffScreenViewport extends Viewport {
         vp._isAspectRatioLocked = lockAspectRatio;
         vp.changeView(view);
         vp._decorationsValid = true;
+        vp.initialize();
         return vp;
     }
     /** @internal */
     get isAspectRatioLocked() {
         return this._isAspectRatioLocked;
     }
-    /** @internal */
+    /** Get the rectangle of this Viewport in [[CoordSystem.View]] coordinates.
+     * @note Do not modify the ViewRect's properties.
+     */
     get viewRect() {
         return this.target.viewRect;
     }