@itwin/core-frontend 4.1.0-dev.6 → 4.1.0-dev.62

package/lib/cjs/Viewport.js

@@ -36,7 +36,7 @@ const ToolSettings_1 = require("./tools/ToolSettings");
 const ViewContext_1 = require("./ViewContext");
 const ViewGlobalLocation_1 = require("./ViewGlobalLocation");
 const ViewingSpace_1 = require("./ViewingSpace");
-const ViewRect_1 = require("./ViewRect");
+const ViewRect_1 = require("./common/ViewRect");
 const ViewStatus_1 = require("./ViewStatus");
 const VisibleFeature_1 = require("./render/VisibleFeature");
 const FlashSettings_1 = require("./FlashSettings");
@@ -95,7 +95,8 @@ exports.ELEMENT_MARKED_FOR_REMOVAL = Symbol.for("@bentley/imodeljs/Viewport/__el
  *
  * 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
  */
@@ -654,7 +655,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) {
@@ -669,7 +670,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,
@@ -679,18 +680,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]].
@@ -751,7 +757,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;
@@ -1140,7 +1148,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();
     }
@@ -1160,7 +1171,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));
@@ -1212,11 +1223,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() {
@@ -2026,7 +2037,9 @@ class Viewport {
         if (requestNextAnimation || undefined !== this._animator || this.continuousRendering)
             IModelApp_1.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.
@@ -2159,7 +2172,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);
                 }
             }
@@ -2293,6 +2310,9 @@ class Viewport {
     onRequestStateChanged() {
         this.invalidateScene();
     }
+    /** @internal See [[OffScreenViewport.drawingToSheetTransform */
+    get drawingToSheetTransform() { return undefined; }
+    set drawingToSheetTransform(_) { (0, core_bentley_1.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 = core_bentley_1.BeDuration.fromSeconds(.5);
@@ -2322,6 +2342,8 @@ exports.Viewport = 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
  */
@@ -2339,6 +2361,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_1.IModelApp.renderSystem.createTarget(canvas));
+        vp.initialize();
         vp.changeView(view);
         return vp;
     }
@@ -2395,7 +2418,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;
@@ -2624,12 +2652,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
@@ -2688,7 +2718,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 */
@@ -2851,7 +2883,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_1.IModelApp.viewManager.hasViewport(this))
             return super.waitForSceneCompletion();
@@ -2946,15 +2978,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
  */
 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;
     }
@@ -2972,13 +3012,16 @@ 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;
     }