@itwin/core-frontend 3.0.0-dev.98 → 3.1.0-dev.0

package/lib/esm/Viewport.js

@@ -5,7 +5,7 @@
 /** @packageDocumentation
  * @module Views
  */
-import { asInstanceOf, assert, BeDuration, BeEvent, BeTimePoint, dispose, Id64, isInstanceOf, ProcessDetector, StopWatch, } from "@itwin/core-bentley";
+import { asInstanceOf, assert, BeDuration, BeEvent, BeTimePoint, dispose, Id64, isInstanceOf, StopWatch, } from "@itwin/core-bentley";
 import { AngleSweep, Arc3d, Geometry, Matrix3d, Plane3dByOriginAndUnitNormal, Point2d, Point3d, Range1d, Range3d, Ray3d, Transform, Vector3d, } from "@itwin/core-geometry";
 import { Camera, ColorDef, Easing, Frustum, GlobeMode, GridOrientationType, Hilite, Interpolation, isPlacement2dProps, Npc, NpcCenter, Placement2d, Placement3d, SubCategoryAppearance, SubCategoryOverride, } from "@itwin/core-common";
 import { ChangeFlag, MutableChangeFlags } from "./ChangeFlags";
@@ -394,9 +394,11 @@ export class Viewport {
     set clipStyle(style) {
         this.displayStyle.settings.clipStyle = style;
     }
-    /** The number of [antialiasing](https://en.wikipedia.org/wiki/Multisample_anti-aliasing) 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.
+    /** Sets the number of [MSAA]($docs/learning/display/MSAA.md) samples for this viewport.
+     * The number of samples is a power of two. Values of 1 or less indicates anti-aliasing should be disabled. Non-power-of-two values are rounded
+     * down to the nearest power of two. The maximum number of samples supported depends upon the client's graphics hardware capabilities. Higher values produce
+     * a higher-quality image but also may also reduce framerate.
+     * @see [[ViewManager.setAntialiasingAllViews]] to adjust the number of samples for all viewports.
      */
     get antialiasSamples() {
         return undefined !== this._target ? this._target.antialiasSamples : 1;
@@ -723,8 +725,8 @@ export class Viewport {
     attachToView() {
         this.registerDisplayStyleListeners(this.view.displayStyle);
         this.registerViewListeners();
-        this.view.attachToViewport();
-        this._mapTiledGraphicsProvider = new MapTiledGraphicsProvider(this);
+        this.view.attachToViewport(this);
+        this._mapTiledGraphicsProvider = new MapTiledGraphicsProvider(this.viewportId, this.displayStyle);
     }
     registerViewListeners() {
         const view = this.view;
@@ -742,7 +744,7 @@ export class Viewport {
             this.setFeatureOverrideProviderChanged();
             this.invalidateRenderPlan();
             this.detachFromDisplayStyle();
-            this._mapTiledGraphicsProvider = new MapTiledGraphicsProvider(this);
+            this._mapTiledGraphicsProvider = new MapTiledGraphicsProvider(this.viewportId, newStyle);
             this.registerDisplayStyleListeners(newStyle);
         }));
         if (view.isSpatialView()) {
@@ -1594,6 +1596,10 @@ export class Viewport {
         var _a;
         (_a = this._animator) === null || _a === void 0 ? void 0 : _a.interrupt();
         this._animator = animator;
+        // Immediately invoke the animator to set up the initial frustum.
+        // This is important for TwoWayViewportSync; otherwise, the synced viewport will have its frustum set to the final frustum,
+        // producing a flicker to that frustum during the first frame of animation.
+        this.animate();
     }
     /** Used strictly by TwoWayViewportSync to change the reactive viewport's view to a clone of the active viewport's ViewState.
      * Does *not* trigger "ViewState changed" events.
@@ -1768,6 +1774,11 @@ export class Viewport {
         this.target.changeRenderPlan(createRenderPlanFromViewport(this));
         this._renderPlanValid = true;
     }
+    animate() {
+        var _a;
+        if ((_a = this._animator) === null || _a === void 0 ? void 0 : _a.animate())
+            this._animator = undefined; // animation completed.
+    }
     /** Renders the contents of this viewport. This method performs only as much work as necessary based on what has changed since
      * the last frame. If nothing has changed since the last frame, nothing is rendered.
      * @note This method should almost never be invoked directly - it is invoked on your behalf by [[ViewManager]]'s render loop.
@@ -1785,8 +1796,7 @@ export class Viewport {
         this._frameStatsCollector.beginTime("totalSceneTime");
         this._frameStatsCollector.beginTime("animationTime");
         // if any animation is active, perform it now
-        if (this._animator && this._animator.animate())
-            this._animator = undefined; // animation completed
+        this.animate();
         this._frameStatsCollector.endTime("animationTime");
         let isRedrawNeeded = this._redrawPending || this._doContinuousRendering;
         this._redrawPending = false;
@@ -1927,18 +1937,28 @@ export class Viewport {
      * @param flipVertically If true, the image is flipped along the x-axis.
      * @returns The contents of the viewport within the specified rectangle as a bitmap image, or undefined if the image could not be read.
      * @note By default the image is returned with the coordinate (0,0) referring to the bottom-most pixel. Pass `true` for `flipVertically` to flip it along the x-axis.
+     * @deprecated Use readImageBuffer.
      */
     readImage(rect = new ViewRect(0, 0, -1, -1), targetSize = Point2d.createZero(), flipVertically = false) {
+        // eslint-disable-next-line deprecation/deprecation
         return this.target.readImage(rect, targetSize, flipVertically);
     }
+    /** Capture the image currently rendered in this viewport, or a subset thereof.
+     * @param args Describes the region to capture and optional resizing. By default the entire image is captured with no resizing.
+     * @returns The image, or `undefined` if the specified capture rect is not fully contained in [[viewRect], a 2d context could not be obtained, or the resultant image consists entirely
+     * of 100% transparent background pixels.
+     */
+    readImageBuffer(args) {
+        return this.target.readImageBuffer(args);
+    }
     /** Reads the current image from this viewport into an HTMLCanvasElement with a Canvas2dRenderingContext such that additional 2d graphics can be drawn onto it.
-     * @see [[readImage]] to obtain the image as a JPEG or PNG.
+     * @see [[readImageBuffer]] to obtain the image as an array of RGBA pixels.
      */
     readImageToCanvas() {
         return this.target.readImageToCanvas();
     }
-    /** Get the point at the specified x and y location in the pixel buffer in npc coordinates
-     * @beta
+    /** Get the point at the specified x and y location in the pixel buffer in npc coordinates.
+     * @see [[getPixelDataWorldPoint]] to obtain the point in [[CoordSystem.World]].
      */
     getPixelDataNpcPoint(pixels, x, y, out) {
         const z = pixels.getPixel(x, y).distanceFraction;
@@ -1959,20 +1979,23 @@ export class Viewport {
             result.z = z;
         return result;
     }
-    /** Get the point at the specified x and y location in the pixel buffer in world coordinates
-     * @beta
+    /** Get the point at the specified x and y location in the pixel buffer in world coordinates.
+     * @see [[getPixelDataNpcPoint]] to obtain the point in [[CoordSystem.Npc]].
      */
-    getPixelDataWorldPoint(pixels, x, y, out) {
+    getPixelDataWorldPoint(args) {
         var _a;
+        const { pixels, x, y, out, preserveModelDisplayTransforms } = args;
         const npc = this.getPixelDataNpcPoint(pixels, x, y, out);
         if (undefined !== npc) {
             this.npcToWorld(npc, npc);
             // If this is a plan projection model, invert the elevation applied to its display transform.
             // Likewise, if it is a hit on a model with a display transform, reverse the display transform.
-            const modelId = (_a = pixels.getPixel(x, y).featureTable) === null || _a === void 0 ? void 0 : _a.modelId;
-            if (undefined !== modelId) {
-                npc.z -= this.view.getModelElevation(modelId);
-                this.view.transformPointByModelDisplayTransform(modelId, npc, true);
+            if (!preserveModelDisplayTransforms) {
+                const modelId = (_a = pixels.getPixel(x, y).featureTable) === null || _a === void 0 ? void 0 : _a.modelId;
+                if (undefined !== modelId) {
+                    npc.z -= this.view.getModelElevation(modelId);
+                    this.view.transformPointByModelDisplayTransform(modelId, npc, true);
+                }
             }
         }
         return npc;
@@ -2232,17 +2255,17 @@ export class ScreenViewport extends Viewport {
         this.addChildDiv(this.vpDiv, div, z);
         return div;
     }
-    /** The HTMLImageElement of the iModel.js logo displayed in this ScreenViewport
+    /** The HTMLImageElement of the iTwin.js logo displayed in this ScreenViewport
      * @beta
      */
     get logo() { return this._logo; }
     /** @internal */
     addLogo() {
         const logo = this._logo = IModelApp.makeHTMLElement("img", { parent: this.vpDiv, className: "imodeljs-icon" });
-        logo.src = "images/imodeljs-icon.svg";
+        logo.src = `${IModelApp.publicPath}images/imodeljs-icon.svg`;
         logo.alt = "";
         const showLogos = (ev) => {
-            const aboutBox = IModelApp.makeModalDiv({ autoClose: true, width: 460, closeBox: true }).modal;
+            const aboutBox = IModelApp.makeModalDiv({ autoClose: true, width: 460, closeBox: true, rootDiv: this.vpDiv.ownerDocument.body }).modal;
             aboutBox.className += " imodeljs-about"; // only added so the CSS knows this is the about dialog
             const logos = IModelApp.makeHTMLElement("table", { parent: aboutBox, className: "logo-cards" });
             if (undefined !== IModelApp.applicationLogoCard)
@@ -2327,6 +2350,7 @@ export class ScreenViewport extends Viewport {
         locateOpts.allowNonLocatable = (undefined === options || !options.excludeNonLocatable);
         locateOpts.allowDecorations = (undefined === options || !options.excludeDecorations);
         locateOpts.allowExternalIModels = (undefined === options || !options.excludeExternalIModels);
+        locateOpts.preserveModelDisplayTransforms = true;
         if (0 !== this.picker.doPick(this, pickPoint, radius, locateOpts)) {
             const hitDetail = this.picker.getHit(0);
             const hitPoint = hitDetail.getPoint();
@@ -2363,7 +2387,7 @@ export class ScreenViewport extends Viewport {
             const npcPt = this.worldToNpc(projectedPt);
             return npcPt.z < 1.0;
         };
-        if (this.view.getDisplayStyle3d().environment.ground.display) {
+        if (this.view.getDisplayStyle3d().environment.displayGround) {
             const groundPlane = Plane3dByOriginAndUnitNormal.create(Point3d.create(0, 0, this.view.getGroundElevation()), Vector3d.unitZ());
             if (undefined !== groundPlane && boresiteIntersect(groundPlane))
                 return { plane: Plane3dByOriginAndUnitNormal.create(projectedPt, groundPlane.getNormalRef()), source: DepthPointSource.GroundPlane };
@@ -2610,15 +2634,15 @@ export class ScreenViewport extends Viewport {
             assert(undefined === this._webglCanvas); // see getter...
             this._webglCanvas = webglCanvas;
             this.addChildDiv(this.vpDiv, webglCanvas, 5);
-            /** The following workaround resolves an issue specific to iOS Safari. We really want this webgl canvas' zIndex to be
-             * lower than this.canvas, but if we do that on iOS Safari, Safari may decide to not display the canvas contents once
-             * it is re-added to the parent div after dropping other viewports. It will only display it once resizing the view.
-             * The offending element here is the 2d canvas sitting on top of the webgl canvas. We need to clear its contents
-             * immediately on iOS. Even though the 2d canvas gets cleared in OnScreenTarget.drawOverlayDecorations() in this case,
-             * it looks like iOS needs an immediate clear.
+            /** We really want this WebGL canvas' zIndex to be lower than this.canvas, but if we do that, browsers can decide to
+             * not update the WebGL canvas contents once it is re-added to the parent div after dropping other viewports.
+             * The offending element is the 2d canvas sitting on top of the WebGL canvas. We need to clear the 2d canvas' contents
+             * in order to ensure browsers allow the underlying WebGL canvas to update. If a decorator is present, the 2d canvas
+             * is cleared during the frame render process by virtue of updating the decorator. For the non-decorator case, and for
+             * iOS, we must make sure we still clear the 2d canvas, done here. iOS appears to need this clear even when decorators
+             * clear the canvas later in the frame render process.
              */
-            if (ProcessDetector.isIOSBrowser)
-                _clear2dCanvas(this.canvas);
+            _clear2dCanvas(this.canvas);
         }
         this.target.updateViewRect();
         this.invalidateRenderPlan();
@@ -2672,7 +2696,7 @@ function _clear2dCanvas(canvas) {
 }
 /** 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]])
+ * 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.
  * @public
  */